better-sqlite3 binding error on macOS ARM64 when using npx
- Dominant language
- TypeScript
- Stars
- 72.6k
- Forks
- 8.6k
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 85
Description
## Description
When running `npx claude-flow@alpha init` on macOS ARM64 (Apple Silicon), the better-sqlite3 native bindings fail to load, resulting in a fallback to in-memory storage.
## Error Message
```
[2025-07-17T18:27:46.202Z] ERROR [memory-store] Failed to initialize: Error: Could not locate the bindings file. Tried:
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/build/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/build/Debug/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/build/Release/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/out/Debug/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/Debug/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/out/Release/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/Release/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/build/default/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/compiled/20.15.0/darwin/arm64/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/addon-build/release/install-root/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/addon-build/debug/install-root/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/addon-build/default/install-root/better_sqlite3.node
→ /Users/nielsvanderwerf/.npm/_npx/7cfa166e65244432/node_modules/better-sqlite3/lib/binding/node-v115-darwin-arm64/better_sqlite3.node
```
## Environment
- **OS**: macOS (Darwin)
- **Architecture**: ARM64 (Apple Silicon)
- **Node Version**: v20.15.0
- **Package**: claude-flow@2.0.0-alpha.61
- **Command**: `npx claude-flow@alpha init`
## Reproduction Steps
1. On a macOS ARM64 machine (M1/M2/M3)
2. Run `npx claude-flow@alpha init`
3. Observe the better-sqlite3 binding error in the console
4. Note that the system falls back to in-memory storage
## Current Behavior
- The application continues to work using the fallback in-memory store
- All features are functional except cross-session persistence
- Users see a warning about using in-memory storage
## Expected Behavior
- Native SQLite bindings should load successfully on ARM64 macOS
- Persistent storage should work out of the box with npx
## Suggested Solutions
### 1. Add ARM64 Build Target
Update `package.json` to include macOS ARM64 in the build targets:
```json
"build:binary": "pkg dist/cli/main.js --targets node20-linux-x64,node20-macos-x64,node20-macos-arm64,node20-win-x64 --output bin/claude-flow"
```
### 2. Enhanced Postinstall Script
Add architecture detection and rebuild logic to `scripts/install.js`:
```javascript
if (process.platform === 'darwin' && process.arch === 'arm64') {
console.log('Detected Apple Silicon, rebuilding better-sqlite3...');
// Add rebuild logic here
}
```
### 3. Prebuilt Binaries
Consider including prebuilt binaries for common architectures or using a package like `prebuild-install`.
### 4. Documentation Update
Add a note in the documentation about this known issue and workarounds for ARM64 users.
## Workarounds
Users can work around this issue by:
1. Installing locally: `npm install -g claude-flow@alpha`
2. Using Docker: `docker run -it claude-flow/claude-flow:alpha`
3. Continuing with in-memory storage (current fallback behavior)
## Additional Context
- The fallback mechanism is working as designed
- This primarily affects npx users on Apple Silicon Macs
- The issue does not affect functionality, only persistence
Contributor guide
Assessment
This issue has not been assessed yet.