ruvnet / ruvnet/ruflo

better-sqlite3 binding error on macOS ARM64 when using npx

Open
#360 2 comments 1 reaction 0 assignees View on GitHub
bug enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.