“BeeRad”andClaude Opus 4.5
0e6bf12ad3
- Fix bootstrap script (.env.example.local → .env.example) - Fix @langchain/core version conflict (^1.0.1 → ^0.3.0) - Add settings:open event listener for LocalKeyGate button - Pin Next.js to 15.1.3 (was "latest") - Default runtime to 'local' mode - Remove desktop app references from UI text - Rewrite MCP docs for web-only context - Add SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md - Add docs/README.md, docs/TROUBLESHOOTING.md - Update README with platform support table 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
Troubleshooting
Installation Issues
npm install fails
Symptom: Error during native module compilation
Fix: Install build tools:
# macOS
xcode-select --install
# Linux
sudo apt install build-essential python3
# Windows
npm install -g windows-build-tools
npm rebuild better-sqlite3 fails
Symptom: Native module rebuild errors
Fix:
- Ensure Node.js 18+ is installed
- Delete
node_modulesand reinstall:rm -rf node_modules package-lock.json npm install npm rebuild better-sqlite3
Runtime Issues
App won't start
Symptom: Error on npm run dev
Fixes:
- Run the bootstrap script first:
scripts/dev/bootstrap-local.sh - Check
.env.localexists (copy from.env.exampleif missing) - Ensure database directory exists:
~/Library/Application Support/RA-H/db/
Vector search returns no results
Symptom: Semantic search doesn't find matches
Fixes:
- Ensure
sqlite-vecextension is loading (check console for errors) - Verify
SQLITE_VEC_EXTENSION_PATHin.env.localpoints tovendor/sqlite-extensions/vec0.dylib - Note: sqlite-vec only works on macOS currently. Linux/Windows users need to compile it manually.
API key validation fails
Symptom: "Invalid key" error in Settings
Fixes:
- Verify key format:
- OpenAI: starts with
sk- - Anthropic: starts with
sk-ant-
- OpenAI: starts with
- Check key has correct permissions/credits
- Try regenerating the key in provider dashboard
Chat returns errors
Symptom: Error messages when chatting
Fixes:
- Check API keys are valid (Settings → API Keys)
- Verify internet connection
- Check browser console for specific error messages
Database Issues
Database locked
Symptom: "SQLITE_BUSY" errors
Fix: Only run one instance of RA-H at a time. Close any other terminals running the app.
Missing tables
Symptom: "no such table" errors
Fix: Re-run the schema script:
scripts/database/sqlite-ensure-app-schema.sh ~/Library/Application\ Support/RA-H/db/rah.sqlite
Platform-Specific
Linux/Windows
The bundled vec0.dylib and yt-dlp binaries are macOS-only. For other platforms:
- sqlite-vec: Build from source at https://github.com/asg017/sqlite-vec
- yt-dlp: Download from https://github.com/yt-dlp/yt-dlp/releases
See the main README for detailed instructions.