Add ADR-0011: the community edition defaults to ~/.waggle-community, a temporary name that follows the product-name decision (Q8), and copies nothing from the commercial ~/.waggle. It supersedes point 4 of ADR-0009 and closes the pending "separate data directory" decision. Update the install guide, troubleshooting, capabilities, memory, architecture, the Windows build notes, THREAT_MODEL, README, .env.example and the changelog. Log UF-068 (Open): marketplace skills and plugins ignore a custom data directory.
143 lines
5.9 KiB
Markdown
143 lines
5.9 KiB
Markdown
# Troubleshooting
|
|
|
|
Common problems and what to do about them. Paths use `<data>` for the data directory:
|
|
`~/.waggle-community` by default (`%USERPROFILE%\.waggle-community` 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.
|