Common issues

Real failure modes from Kanade development sessions. If you hit something not listed here, copy diagnostics from /about and send them through the tracker or support channel configured for your build so the docs can catch up.

Symptom: the kanade tile in Start shows a generic icon (not the kin-gold 奏 disc) and clicking it does nothing.

Cause: the Start Menu shortcut points at %LOCALAPPDATA%\kanade\kanade-desktop.exe but the binary isn’t there. Usually because of an interrupted uninstall or a manual cleanup pass that removed the .exe but left the data directory.

Fix: re-run the installer. Your data (accounts.json, kanade.db, logs/) survives intact.

Start-Process -FilePath ".\kanade_0.1.0_x64-setup.exe" -ArgumentList "/S","/CURRENTUSER" -Wait

After install, the shortcut target resolves again and the icon shows up. If the icon is still generic after launch, sign out and back in to refresh Windows’ icon cache, or run ie4uinit.exe -show.

”The daemon won’t start”

Symptom: the desk window opens but everything reads “no active session”; the tray icon never goes green.

First check: open the tray menu → Reveal logs to open %LOCALAPPDATA%\kanade\logs\ in Explorer. Look at the most recent daemon-*.log. Common causes:

Port already in use — kanade picks a random loopback port at launch, but if something on your machine is hogging an unusual range, it may fail. The log line OSError: [WinError 10048] is the signature.
WebView2 not installed — rare on Win11, more common on Win10. The log will mention WebView2Loader. Install the WebView2 runtime from Microsoft.

The supervisor will retry the daemon up to 3 times in 60 seconds with exponential backoff. If it gives up, the tray icon stays red — quit fully and relaunch.

”The app says Failed to fetch after I come back”

Symptom: /tsukue loads, but the chat pane cannot hydrate prior history and the center of the desk says “Failed to fetch” or “Couldn’t load prior history.”

Cause: the browser is alive but the daemon API is not answering cleanly. During source testing this has most often meant the daemon was restarted, the Vite proxy briefly saw ECONNREFUSED, or the SQLite chronicle returned database disk image is malformed.

Fix: reload once after the daemon is green. Current source keeps the desk usable and shows a retry affordance instead of blocking the whole chat pane. If the daemon log contains database disk image is malformed, preserve the current DB files first, then let Kanade rebuild from the hook spool:

$data = "$env:LOCALAPPDATA\kanade\data"
$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$backup = "$data\db-corrupt-backup-$stamp"
New-Item -ItemType Directory -Path $backup | Out-Null
Move-Item "$data\kanade.db*" $backup

Then restart the daemon. The hook spool (~\.claude\kanade\events.jsonl) is the source of truth for observatory history, so a fresh DB can re-index it. Direct-mode conversations also live in SQLite; if you have direct chats you care about, keep that backup folder.

”Is my desktop app actually on the latest update?”

Open Settings -> Desktop update channel. The read-only check shows:

the version currently running,
the version advertised by https://kanade.jhinx.dev/updates/latest.json,
whether the manifest has a Tauri updater signature,
whether the advertised Windows installer payload returns HTTP 200,
the payload size.

This section does not install anything. The actual updater still runs through the desktop update banner so the signed Tauri installer and relaunch flow are used.

”DeepSeek says 401 but my key works elsewhere”

Symptom: the DeepSeek lane reports a 401 such as “failed to authenticate” while the same key appears to work in another client.

Open Settings -> Accounts & Providers, pick the DeepSeek lane, then click test. Kanade will show:

the provider it inferred,
the configured base URL,
the normalized DeepSeek test URL,
the model id,
the key source without revealing the key.

Common causes:

Wrong source wins. An account override shadows process env. If the lane says the key source is an account override, use replace key to update it or remove that env override from the lane.
PowerShell alias vs Kanade config drift. A ccp alias may have been updated outside Kanade. Use reload account config after editing accounts.json, then stop/start the lane.
Wrong endpoint shape. Claude Code router lanes often use DeepSeek’s Anthropic-compatible base URL, while Kanade’s connection test verifies the same key/model against DeepSeek’s OpenAI-compatible chat endpoint. The UI shows both the configured base URL and the normalized test URL.
Provider really rejected the key. If the test returns auth_rejected, DeepSeek rejected the active key Kanade resolved. Rotate or replace that key.

Kanade never prints the full key in the UI, logs, or docs.

”DeepSeek hangs when I send an image”

Symptom: an image is pasted or dropped into the DeepSeek lane, Kanade shows a Read tool row for the local file, but no useful answer appears for a long time.

Cause: DeepSeek’s current public API docs list text/chat, thinking, JSON, tool calls, prefix completion, and FIM features for deepseek-v4-flash and deepseek-v4-pro; they do not list image/vision input as a supported API feature. In practice, Claude can consume @<image path> through Claude Code, while DeepSeek-router lanes may only read the file path or stall around the wrapper/tool layer.

What Kanade does: pasted images still save and preview correctly, and the path is sent as @<path> exactly like a terminal prompt. If the provider wrapper does not finish, Kanade stops the turn after KANADE_SEND_TURN_TIMEOUT_S seconds (default 180) and writes a system notice instead of leaving the lane loading forever.

Use Claude for image-reading work until DeepSeek documents and exposes vision support through the route you are using.

”Changing Claude model still answers as the old model”

Symptom: you select Sonnet in Kanade, ask “what model are you using?”, and Claude Code still answers as Opus.

Cause: Claude Code does not expose Kanade’s --effort flag to the model’s self-report, and model changes in resumed sessions are best treated as a requested runtime flag rather than something the assistant can introspect.

Fix in current source: Kanade now shows the requested model/effort in the bottom proof chip and sends the real --model / --effort flags on the next chat turn. The cached resume target is preserved where possible so context can continue. Trust Kanade’s proof chip and logs over the assistant’s self-report; use /clear when you want a fresh underlying session.

For direct checks, use Kanade’s bottom proof chip and logs. The chat path no longer intercepts model/effort questions; those turns stay with the active lane until Kanade has a durable routing policy.

”Claude says No conversation found with session ID”

Symptom: a Claude lane shows No conversation found with session ID after returning to a lane, switching project folders, or restarting the daemon.

Cause: Kanade cached a Claude Code resume id, but Claude Code no longer has the transcript file for that conversation. A resume id is only useful while the underlying Claude project/session store still contains it.

Fix in current source: Kanade validates daemon-owned cached resume ids against the observed transcript path before sending --resume. If the transcript is missing, Kanade clears the cached id, starts a fresh turn, and adds a system notice explaining that the stale resume was dropped.

The Sessions tab also checks provider compatibility before arming a resume. If a row says not this lane, switch to the matching lane or open the session for inspection instead. For example, a Codex-native transcript should be resumed from a Codex lane, not a DeepSeek lane.

”Codex screenshot paste says trusted directory or no prompt provided”

Symptom: after pasting an image into a Codex lane, the response says Not inside a trusted directory and --skip-git-repo-check was not specified, or Codex exits with No prompt provided via stdin.

Cause: Codex needs pasted images as native --image <path> arguments, and Kanade’s local paste cache may sit outside a git-trusted project directory. A previous wrapper shape also let image paths consume the prompt argument.

Fix in v0.2.19: Kanade now adds --skip-git-repo-check, passes pasted image refs as repeated --image arguments, and terminates those variadic args before the prompt/session id. Pasted screenshots should preview in the user bubble and then reach Codex as image input.

”LM Studio not reachable”

Symptom: every other surface works, but /yume says “voice unavailable” and the per-session chronicle never gets its narration paragraph.

Click Settings -> Voice runtime -> test connection first. The test now checks GET /v1/models, normalizes trailing slashes and /v1, and retries 127.0.0.1 if localhost fails.

Causes, in order of frequency:

LM Studio’s server isn’t running. Open LM Studio → Local Server → click Start. The default port is 1234.
The URL in kanade Settings is wrong. The default is http://localhost:1234/v1. If you run LM Studio on a different machine, use that machine’s IP, not localhost.
The model isn’t listed. If the server is reachable but your configured model is missing, copy the model id from the /v1/models response or load the model in LM Studio.
Auto-unload kicked in. LM Studio can auto-unload models after a few minutes of idle. Turn auto-unload OFF in LM Studio server settings — kanade makes calls infrequently and you’ll get false “unavailable” reads.

To test from a shell:

curl http://localhost:1234/v1/models

If that lists models, Kanade should be able to reach LM Studio. If the Settings test says model_missing, update the configured model id.

”I want to export / move / wipe my data”

All of your kanade data lives in two directories:

%LOCALAPPDATA%\kanade\ — binaries + user data (accounts.json, the SQLite chronicle, logs).
%APPDATA%\kanade\ — your wizard config (env.json, config.json).

To back up: copy both directories. To migrate to a new machine: install on the new machine, then drop your saved copies over the freshly-created versions before first launch. To wipe everything: uninstall, then delete both directories manually. (The uninstaller deliberately leaves them so you don’t lose history on a reinstall.)

”SmartScreen blocks the installer”

The build isn’t code-signed yet (signing is on the post-alpha roadmap). The prompt is one-time: click More info → Run anyway.

If you’d rather verify the file is the one we sent you, check its SHA-256 against the hash in the issue thread where you received the link.