This commit is contained in:
Oleg Maslov
207
docs/guides/troubleshooting.md
Normal file
207
docs/guides/troubleshooting.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common issues, error codes, and solutions.
|
||||
|
||||
## API Key Issues
|
||||
|
||||
### "No API key configured"
|
||||
|
||||
The agent cannot run without an LLM provider key.
|
||||
|
||||
**Fix:** Go to Settings > Models and add your Anthropic key (starts with `sk-ant-`). Or edit `~/.waggle/config.json` directly:
|
||||
|
||||
```json
|
||||
{
|
||||
"defaultModel": "claude-sonnet-4-6",
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"apiKey": "sk-ant-your-key-here",
|
||||
"models": ["claude-sonnet-4-6"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### "API key is too short" / "must start with sk-ant-"
|
||||
|
||||
The key format validation failed.
|
||||
|
||||
**Fix:** Anthropic keys must start with `sk-ant-` and be at least 20 characters. OpenAI keys start with `sk-`. Copy the full key from your provider dashboard.
|
||||
|
||||
### Key works in API but not in Waggle
|
||||
|
||||
The built-in Anthropic proxy translates OpenAI-format requests to Anthropic format. If you are using a non-standard provider, you may need LiteLLM as a proxy:
|
||||
|
||||
```bash
|
||||
docker compose up litellm
|
||||
```
|
||||
|
||||
Then set your LiteLLM URL in Settings > Advanced.
|
||||
|
||||
## Server Issues
|
||||
|
||||
### Server won't start
|
||||
|
||||
**Check port availability:**
|
||||
```bash
|
||||
# Is port 3333 already in use?
|
||||
lsof -i :3333 # macOS/Linux
|
||||
netstat -ano | findstr 3333 # Windows
|
||||
```
|
||||
|
||||
**Fix:** Kill the existing process or change the port:
|
||||
```bash
|
||||
PORT=3334 npx tsx src/local/start.ts
|
||||
```
|
||||
|
||||
### "SQLITE_CANTOPEN" error
|
||||
|
||||
The `.mind` database file cannot be opened.
|
||||
|
||||
**Fix:**
|
||||
- Check that `~/.waggle/` exists and is writable
|
||||
- Check that no other process has the `.mind` file locked
|
||||
- If the file is corrupted, rename it (data will be lost) and let Waggle create a fresh one
|
||||
|
||||
### Server crashes with "out of memory"
|
||||
|
||||
Large workspace minds or many concurrent operations can exhaust memory.
|
||||
|
||||
**Fix:**
|
||||
- Restart the server
|
||||
- If recurring, check your mind file size: `ls -la ~/.waggle/default.mind`
|
||||
- Consider running memory consolidation: `POST /api/cron/{consolidation-id}/trigger`
|
||||
|
||||
## Memory Issues
|
||||
|
||||
### Memory not saving
|
||||
|
||||
Memories are saved automatically during conversations when the agent determines something is important.
|
||||
|
||||
**Check:**
|
||||
1. Verify the workspace mind path exists: `~/.waggle/workspaces/{id}/workspace.mind`
|
||||
2. Check that the disk has free space
|
||||
3. Try saving explicitly: "Remember that [important fact]"
|
||||
|
||||
### Search returns no results
|
||||
|
||||
FTS5 search requires at least 3 characters.
|
||||
|
||||
**Fix:**
|
||||
- Use longer queries (3+ characters)
|
||||
- Check you are searching the right scope (personal, workspace, or all)
|
||||
- Verify memories exist: open the Memory tab in the right panel
|
||||
|
||||
### Memory from another workspace showing up
|
||||
|
||||
This is expected behavior. The agent searches both personal and workspace minds. Personal mind memories are shared across all workspaces.
|
||||
|
||||
**Fix:** If a memory should be workspace-specific, it should have been saved to the workspace mind (this happens automatically for project-specific context).
|
||||
|
||||
## Connector Issues
|
||||
|
||||
### "Vault not available"
|
||||
|
||||
The encrypted vault database failed to initialize.
|
||||
|
||||
**Fix:**
|
||||
- Check that `~/.waggle/` is writable
|
||||
- If `~/.waggle/vault.db` exists but is corrupted, rename it and restart
|
||||
- The vault auto-migrates from plain config.json on first access
|
||||
|
||||
### Connector shows "disconnected" after restart
|
||||
|
||||
Credentials persist in the vault across restarts. If a connector shows disconnected:
|
||||
|
||||
1. Check the health endpoint: `GET /api/connectors/{id}/health`
|
||||
2. If the token expired, re-connect with fresh credentials
|
||||
3. If the service is unreachable, check your network
|
||||
|
||||
### "Connector not found" (404)
|
||||
|
||||
Connector IDs are lowercase. Use `GET /api/connectors` to see all registered IDs.
|
||||
|
||||
### Approval gate stuck
|
||||
|
||||
If an approval card appears but you cannot click Approve/Deny:
|
||||
|
||||
**Fix:**
|
||||
1. Check `GET /api/approval/pending` to see pending approvals
|
||||
2. Approve via API: `POST /api/approval/{requestId}` with `{"approved": true}`
|
||||
3. If the request expired, send a new message to the agent
|
||||
|
||||
## Desktop App Issues
|
||||
|
||||
### White screen after launch
|
||||
|
||||
The Tauri WebView2 runtime may not be installed (Windows).
|
||||
|
||||
**Fix:** Download and install the [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
|
||||
|
||||
### Sidecar not starting
|
||||
|
||||
The Node.js sidecar needs Node.js 20+ in the system PATH.
|
||||
|
||||
**Fix:**
|
||||
- Install Node.js 20+ from https://nodejs.org
|
||||
- Restart the app after installation
|
||||
- Check the Tauri console for error messages
|
||||
|
||||
### Notifications not appearing (Windows)
|
||||
|
||||
**Fix:**
|
||||
- Check Windows notification settings for Waggle
|
||||
- Ensure "Focus Assist" is not blocking notifications
|
||||
- The app must be running (tray icon visible)
|
||||
|
||||
## Team Mode Issues
|
||||
|
||||
### Cannot connect to team server
|
||||
|
||||
**Check:**
|
||||
- The server URL is correct (include `https://`)
|
||||
- The auth token is valid
|
||||
- The team server is reachable: `curl https://your-server/health`
|
||||
|
||||
### "Team server connection timed out"
|
||||
|
||||
**Fix:** The team server health check has a 5-second timeout. Check that:
|
||||
- The server is running
|
||||
- There are no firewall rules blocking the connection
|
||||
- DNS resolves correctly
|
||||
|
||||
### Tasks not syncing
|
||||
|
||||
Task data is stored per-workspace in JSONL files. In team mode, tasks are stored on the team server.
|
||||
|
||||
**Fix:** Check team connection status: `GET /api/team/status`
|
||||
|
||||
## Common Error Codes
|
||||
|
||||
| Code | Meaning | Fix |
|
||||
|------|---------|-----|
|
||||
| 400 | Bad request -- missing or invalid parameters | Check the API reference for required fields |
|
||||
| 404 | Resource not found | Verify the ID/name exists |
|
||||
| 409 | Conflict -- resource already exists | The skill/plugin is already installed |
|
||||
| 413 | File too large | Files must be under 10 MB |
|
||||
| 503 | Service unavailable | The required service (vault, marketplace, plugin runtime) is not ready |
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Where is my data stored?**
|
||||
A: All data is in `~/.waggle/` on your machine. Nothing is sent to cloud servers unless you explicitly connect a team server or external service.
|
||||
|
||||
**Q: Can I move my data to another machine?**
|
||||
A: Yes. Copy the entire `~/.waggle/` directory. The `.mind` files are portable SQLite databases.
|
||||
|
||||
**Q: How do I reset everything?**
|
||||
A: Delete `~/.waggle/` and restart. Waggle creates fresh defaults on startup.
|
||||
|
||||
**Q: Which LLM models work?**
|
||||
A: Waggle works best with Claude (Anthropic). It also supports OpenAI, Google Gemini, and any model available through LiteLLM. The built-in proxy handles Anthropic natively.
|
||||
|
||||
**Q: How much does it cost to run?**
|
||||
A: Waggle itself is free. You pay only for LLM API usage. The Cockpit status bar shows estimated cost per session. A typical conversation costs $0.05-0.50 depending on length and model.
|
||||
|
||||
**Q: Can I use it offline?**
|
||||
A: Waggle requires an LLM API connection for agent responses. Memory, workspace management, and the UI work offline.
|
||||
Reference in New Issue
Block a user