diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 51a21fb..2255eb3 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -1,207 +1,141 @@ # Troubleshooting -Common issues, error codes, and solutions. +Common problems and what to do about them. Paths use `` for the data directory: +`~/.waggle` by default (`%USERPROFILE%\.waggle` on Windows), or `WAGGLE_DATA_DIR`. -## API Key Issues +## Installing -### "No API key configured" +### Windows or macOS refuses to open the installer or the app -The agent cannot run without an LLM provider key. +The first release is not signed. See [install.md](../install.md): on Windows choose **More +info** → **Run anyway**; on macOS use **Open Anyway** in System Settings → Privacy & Security, or +`xattr -dr com.apple.quarantine /Applications/Waggle.app`. -**Fix:** Go to Settings > Models and add your Anthropic key (starts with `sk-ant-`). Or edit `~/.waggle/config.json` directly: +### The AppImage does not start on Linux -```json -{ - "defaultModel": "claude-sonnet-4-6", - "providers": { - "anthropic": { - "apiKey": "sk-ant-your-key-here", - "models": ["claude-sonnet-4-6"] - } - } -} -``` +Install FUSE 2 (`libfuse2` or `libfuse2t64` on Ubuntu, `fuse-libs` on Fedora), or use the `.deb`. -### "API key is too short" / "must start with sk-ant-" +### The server installer stops with an error -The key format validation failed. +| Message | What to do | +|---|---| +| "This build has no download location yet. Pass --from …" | The default download location is not set yet. Pass the archive: `--from ` | +| "There is no Waggle server build for …" | Your system is not supported. Builds exist for Windows x64, macOS (Apple silicon and Intel) and Linux x64 | +| "The archive checksum does not match" | The download is damaged or not the published file. Download it again | +| "No checksum found at ….sha256" | The `.sha256` file is missing next to the archive URL. Pass `--sha256 ` if you have the checksum from another source | +| "This archive is for …; this system needs …" | You downloaded the archive for another system | +| "Windows cannot update the program it is running" | Stop the server, then run `npx @waggle-ai/waggle update` (or `uninstall`) | +| "Waggle needs Node.js 20 or newer to install" | Update Node.js for the `npx` call; Waggle itself runs on its own Node.js | -**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. +Run `waggle-server doctor` to check an existing installation. -### Key works in API but not in Waggle +## Starting -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: +### The desktop app stays on "Starting Waggle…" + +Close the app and look at the server log: `/logs/service.log` (the previous run is in +`service.log.1`). It usually names the problem, such as a data directory that is not writable. + +On Windows, Waggle needs the WebView2 runtime, which ships with current Windows 10 and 11. If the +window stays white, install WebView2 from Microsoft. + +### Port 3333 is in use + +The desktop app picks another free port by itself. For the server installer: ```bash -docker compose up litellm +waggle-server --port 3334 ``` -Then set your LiteLLM URL in Settings > Advanced. +When running from source: `WAGGLE_PORT=3334 npm run dev:server`. -## Server Issues +To see what uses the port: `lsof -i :3333` on macOS and Linux, `netstat -ano | findstr 3333` on +Windows. -### Server won't start +### The page is blank or assets return 404 (running from source) -**Check port availability:** -```bash -# Is port 3333 already in use? -lsof -i :3333 # macOS/Linux -netstat -ano | findstr 3333 # Windows -``` +The sidecar registers the files in `dist/` when it starts. After `npm run build`, restart it. +Use the UI the sidecar serves at http://localhost:3333; the Vite dev server (`npm run dev:web`) +cannot sign in to the sidecar yet. -**Fix:** Kill the existing process or change the port: -```bash -PORT=3334 npx tsx src/local/start.ts -``` +## Models -### "SQLITE_CANTOPEN" error +### "No AI model is ready" -The `.mind` database file cannot be opened. +Chat needs at least one working model. Add a provider key in **Settings** → **Models** (API key +tab), or install the private runtime and a local model there (Local model tab). -**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 +### A provider key is rejected -### Server crashes with "out of memory" +Copy the whole key again from the provider's console. Waggle checks the key's format and, when +the provider is reachable, tests it. A key that worked before can stop working when the provider +account runs out of credit or the key is revoked. -Large workspace minds or many concurrent operations can exhaust memory. +### Local model downloads are slow or large -**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` +The managed Ollama runtime and the models are large downloads (the Linux runtime alone is about +1.4 GB). They are stored in `/runtimes/ollama` and `/models/ollama`. Keep the window +open until the download is verified. -## Memory Issues +## Memory -### Memory not saving +### Waggle does not remember something -Memories are saved automatically during conversations when the agent determines something is important. +- Say it explicitly: "Remember that …". +- Check the scope. Workspace memories are only recalled in their workspace; personal memories + everywhere. `/search-all ` searches all workspaces. +- Open **Memory** and search for it. If it is there but marked temporary, it is not recalled. -**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]" +### "Learn facts about me from chats" is not available -### Search returns no results +Background fact extraction needs a model. Set one up in **Settings** → **Models**. -FTS5 search requires at least 3 characters. +### "This memory store was built with embedder …" -**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 +The memory store was created with another embedding model, whose vectors cannot be compared with +the current one. Switch back to that model, or quit Waggle and move `/memory/` aside to +start a new, empty store. -### Memory from another workspace showing up +### Memory needs a network connection the first time -This is expected behavior. The agent searches both personal and workspace minds. Personal mind memories are shared across all workspaces. +The embedding model used by memory is downloaded on first use into `/models/`. After that, +memory works offline. -**Fix:** If a memory should be workspace-specific, it should have been saved to the workspace mind (this happens automatically for project-specific context). +## Connectors and channels -## Connector Issues +See [connectors.md](connectors.md#troubleshooting). -### "Vault not available" +## Your data -The encrypted vault database failed to initialize. +### Where is my data? -**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 +In ``; [install.md](../install.md#where-your-data-lives) lists what each file holds. Data +leaves your computer only for the services you set up (model providers, connectors, channels, +marketplace sources) and, if you allowed analytics, one setup event without your chats, files or +memories. -### Connector shows "disconnected" after restart +### Move Waggle to another computer -Credentials persist in the vault across restarts. If a connector shows disconnected: +Quit Waggle and copy the whole data directory. On the new computer, install Waggle and put the +directory in the same place (or point `WAGGLE_DATA_DIR` at it). The Vault key (`.vault-key`) +must travel with `vault.json`, or the stored secrets cannot be read. -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 +### Start over -### "Connector not found" (404) +Quit Waggle and delete the data directory, or use **Settings** → **General** → **Erase all my +data**, which wipes it the next time Waggle starts. Data you already sent to cloud model providers +is not erased by this; ask those providers. -Connector IDs are lowercase. Use `GET /api/connectors` to see all registered IDs. +## Questions -### Approval gate stuck +**Which models work?** Models from Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba, +MiniMax, Zhipu, Moonshot, Perplexity and OpenRouter with your own key, and local models through +Ollama. -If an approval card appears but you cannot click Approve/Deny: +**What does it cost?** Waggle is free. You pay your model provider for what you use. **Usage & +Cost** shows the estimated cost of your model calls, and Settings → Models can set a daily +budget. -**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. +**Does it work offline?** With a local model, yes, once the runtime, the model and the embedding +model are downloaded. With a provider key, chat needs a connection to that provider; your +workspaces, files and memory stay available offline.