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.
5.9 KiB
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: 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:
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.
Your data
Where is my data?
In <data>; install.md 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.