Files
waggle-os/docs/guides/troubleshooting.md
shumeiko.it 94d54c4188 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.
2026-11-01 01:59:25 +01:00

142 lines
5.9 KiB
Markdown

# Troubleshooting
Common problems and what to do about them. Paths use `<data>` for the data directory:
`~/.waggle` by default (`%USERPROFILE%\.waggle` on Windows), or `WAGGLE_DATA_DIR`.
## Installing
### Windows or macOS refuses to open the installer or the app
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`.
### The AppImage does not start on Linux
Install FUSE 2 (`libfuse2` or `libfuse2t64` on Ubuntu, `fuse-libs` on Fedora), or use the `.deb`.
### The server installer stops with an error
| 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 <path or URL>` |
| "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 <hex>` 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 |
Run `waggle-server doctor` to check an existing installation.
## Starting
### The desktop app stays on "Starting Waggle…"
Close the app and look at the server log: `<data>/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
waggle-server --port 3334
```
When running from source: `WAGGLE_PORT=3334 npm run dev:server`.
To see what uses the port: `lsof -i :3333` on macOS and Linux, `netstat -ano | findstr 3333` on
Windows.
### The page is blank or assets return 404 (running from source)
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.
## Models
### "No AI model is ready"
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).
### A provider key is rejected
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.
### Local model downloads are slow or large
The managed Ollama runtime and the models are large downloads (the Linux runtime alone is about
1.4 GB). They are stored in `<data>/runtimes/ollama` and `<data>/models/ollama`. Keep the window
open until the download is verified.
## Memory
### Waggle does not remember something
- Say it explicitly: "Remember that …".
- Check the scope. Workspace memories are only recalled in their workspace; personal memories
everywhere. `/search-all <query>` searches all workspaces.
- Open **Memory** and search for it. If it is there but marked temporary, it is not recalled.
### "Learn facts about me from chats" is not available
Background fact extraction needs a model. Set one up in **Settings** → **Models**.
### "This memory store was built with embedder …"
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 `<data>/memory/` aside to
start a new, empty store.
### Memory needs a network connection the first time
The embedding model used by memory is downloaded on first use into `<data>/models/`. After that,
memory works offline.
## Connectors and channels
See [connectors.md](connectors.md#troubleshooting).
## Your data
### Where is my data?
In `<data>`; [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.
### Move Waggle to another computer
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.
### Start over
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.
## Questions
**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.
**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.
**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.