“BeeRad”
21772fcba7
- Add MCP setup, doctor, init-db, config, and rules CLI commands - Publish latest MCP package wiring and local setup helper - Update OS install docs for MCP-only, full app, and demo-safe setup Generated with Claude Code
101 lines
2.3 KiB
Markdown
101 lines
2.3 KiB
Markdown
# Troubleshooting
|
|
|
|
## Installation Issues
|
|
|
|
### `npm install` fails
|
|
|
|
**Symptom:** Error during native module compilation
|
|
|
|
**Fix:** Install build tools:
|
|
```bash
|
|
# macOS
|
|
xcode-select --install
|
|
|
|
# Linux
|
|
sudo apt install build-essential python3
|
|
|
|
# Windows
|
|
npm install -g windows-build-tools
|
|
```
|
|
|
|
### `npm run setup:local` fails
|
|
|
|
**Symptom:** Native module rebuild errors
|
|
|
|
**Fix:**
|
|
1. Ensure Node.js 20.18.1+ is installed
|
|
2. Delete `node_modules` and reinstall:
|
|
```bash
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
npm run setup:local
|
|
```
|
|
|
|
## Runtime Issues
|
|
|
|
### App won't start
|
|
|
|
**Symptom:** Error on `npm run dev`
|
|
|
|
**Fixes:**
|
|
1. Run local setup first: `npm run setup:local`
|
|
2. Check `.env.local` exists (copy from `.env.example` if missing)
|
|
3. Ensure database directory exists: `~/Library/Application Support/RA-H/db/`
|
|
|
|
### Vector search returns no results
|
|
|
|
**Symptom:** Semantic search doesn't find matches
|
|
|
|
**Fixes:**
|
|
1. Ensure `sqlite-vec` extension is loading (check console for errors)
|
|
2. Verify `SQLITE_VEC_EXTENSION_PATH` in `.env.local` points to `vendor/sqlite-extensions/vec0.dylib`
|
|
3. 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:**
|
|
1. Verify key format:
|
|
- OpenAI: starts with `sk-`
|
|
- Anthropic: starts with `sk-ant-`
|
|
2. Check key has correct permissions/credits
|
|
3. Try regenerating the key in provider dashboard
|
|
|
|
### Chat returns errors
|
|
|
|
**Symptom:** Error messages when chatting
|
|
|
|
**Fixes:**
|
|
1. Check API keys are valid (Settings → API Keys)
|
|
2. Verify internet connection
|
|
3. 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:
|
|
```bash
|
|
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:
|
|
|
|
1. **sqlite-vec**: Build from source at https://github.com/asg017/sqlite-vec
|
|
2. **yt-dlp**: Download from https://github.com/yt-dlp/yt-dlp/releases
|
|
|
|
See the main README for detailed instructions.
|