wikai
Download

Troubleshooting

An agent shows “needs install”

Wikai can’t find the Claude Code or Codex CLI, or it isn’t signed in. Install it, sign in once in a terminal (claude /login or codex login), and click Re-detect on that agent’s tab in Settings. If it’s installed somewhere unusual, set the path with Use a different binary. No subscription? OpenRouter, the Anthropic API, or a local model need no CLI at all.

A local model shows “cannot reach”

Wikai probes the address you gave it. Check the server is running and listening on that address and port, that the URL ends in /v1, and — for a server on another machine — that the port is reachable from this one. The tab shows the server’s answer, or the error, so you can see which it is.

An external MCP client stopped connecting

Starting with 0.5.0, the local MCP endpoint requires a bearer token. If a previously working client returns 401 Unauthorized, open Settings → Agents → MCP server, click Copy client config (JSON), and update the client’s configuration with both the endpoint and authorization header. Don’t overwrite unrelated server entries. Reload the connection afterward.

  • 401 means the bearer token is missing or incorrect. The token only changes when you press Generate new in Settings — if someone did, copy the configuration again.
  • 403 means the request includes an Origin header. Browser-page connections are blocked even with a valid token; use a local MCP client.
  • Connection refused: confirm Wikai is running and compare the endpoint with Settings. The port is chosen once and kept; it only moves if it was busy at launch, and then Wikai tells you — a toast at launch, a notice in Settings — and keeps the new one. Copy the configuration again.

Wikai handles authentication for its own chat agents automatically. Never include the token or an unredacted client configuration in a bug report. See MCP setup.

The chat says Claude Code started without Wikai’s tools

An amber line at the top of a turn means Claude Code’s own MCP roll call had no working wikai server, so every wiki read or write in that turn will fail. The line says which: the server is disabled for the project your wiki’s folder belongs to (disabledMcpServers in ~/.claude.json — re-enable it there, or move the wiki out of that project), it failed to connect (check Settings → MCP server, then start a new chat), or it is missing from the roll call altogether.

A PowerPoint file is stored but has no wiki pages

.pptx has no importer yet. Wikai keeps the file under raw/ and reports it as stored, not ingested. Export the presentation to PDF and import that. See files Wikai can’t read.

An EPUB is stored but has no chapters

The book is DRM-protected — the amber row names the scheme (Adobe ADEPT, Apple FairPlay or Readium LCP). Wikai does not remove DRM. A DRM-free copy from the same publisher, or a watermarked one, imports normally.

An ingest is slow, or looks stuck

Open the ingest panel. If it says System memory is low since page N, the machine is short of memory and those pages are taking longer — closing other apps helps, and the note clears when memory recovers. Settings → App → Diagnostics shows the same picture: Wikai’s own footprint and the system’s available memory and pressure level. Wikai itself stays small — around 50 MB idle and under 600 MB while reading a large document — so a machine under pressure is usually busy with something else.

Concept search says “warming up”

The first semantic search loads the embedding model, which ships inside the app; give it a moment. After ten idle minutes the model is unloaded to keep Wikai’s footprint small, so the first search after a quiet spell warms up again.

Wikai asks me to pick a wikis folder

On first launch Wikai creates Documents/Wikai on its own and never asks. If you see a setup form instead, it couldn’t create that folder or write its config file. Make sure your Documents folder and the app’s config directory (see Settings) are writable, then pick or create a folder in the form. If the form comes back on every launch, the config file itself isn’t being saved — the log under Settings → Diagnostics says why.

Windows SmartScreen warns about the installer

The installer is signed — but a signing certificate has to build reputation with Microsoft before SmartScreen stops asking, and ours is new. Until it does, you may see a caution. Choose More info → Run anyway.

You don’t have to take our word for it: right-click the .msi → Properties → Digital Signatures and confirm the signer reads Atomic BITS. See verifying your download.

Still stuck?

Email support@wikai.app with what you did, what you expected, and what happened.

Last updated 2026-10-07.