From 94d54c41888e60eb159a2bbc9bab4e4da93c257e Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sun, 1 Nov 2026 01:59:25 +0100 Subject: [PATCH] docs: rewrite the troubleshooting guide for this edition (P2.4) Cover the unsigned installers, the server installer's error messages, the desktop startup log, ports, models, memory on mem0 (including the embedder mismatch) and the data directory. Drop team mode, the .mind files, FTS5, docker compose for LiteLLM, the Node-on-PATH requirement of the old desktop app and the invented cost per conversation. --- docs/guides/troubleshooting.md | 252 ++++++++++++--------------------- 1 file changed, 93 insertions(+), 159 deletions(-) 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.