Troubleshooting
A symptom-first index for Kunai: provider failures, playback crashes, network problems, setup errors, and poster issues, each with concrete fix steps.
Use this page when something fails during normal use. Start with /diagnostics inside Kunai; it shows provider timelines, cache state, mpv status, and network snapshots without exposing stream URLs.
Most failures turn out to be provider failures. Kunai cannot resurrect a dead mirror; it can put the next source one keypress away. That is the whole recovery model.
For exportable evidence, run /export-diagnostics before closing the shell. See Diagnostics and reporting for privacy rules.
Quick triage
Reproduce with diagnostics open
Launch with --debug if the failure happens at startup:
kunai --debug -S "Title"Then open /diagnostics during or after the failure.
Try recovery before reconfiguring
ror/recover: refresh current provider stream⇧F(Shift+F) or/fallback: next compatible provider/recompute: bypass stale cache for current episode
Export evidence if you need help
/export-diagnostics
/report-issueReview the bundle locally before sharing. It must not contain raw stream URLs or tokens.
Provider resolve failed
Symptoms: Search works but playback never starts; resolve spinner stops with a provider error; /diagnostics shows failed resolve stages.
What to try
- Open
/diagnosticsand read the provider attempt timeline. - Note the failure class (timeout, empty inventory, HTTP error, offline/network).
- Press
⇧F(Shift+F) or/fallbackto try the next provider in your priority list. - If yesterday's provider still wins and always fails, run
/reset-provider-healthso auto-fallback can retry it./clear-cachedrops cached stream URLs (optionally health memory too). - If one provider always fails, check Customization for
providerPriority/animeProviderPriority. - For domain drift, update Kunai: media-provider domains (movie/TV + anime) are compiled in and no override file is read. Exception: YouTube metadata endpoints are configurable via
youtubeMetadata.instanceUrl/youtubeMetadata.pipedApiUrlin settings/config, no rebuild needed. A user-owned relay (providerRelay.baseUrlin settings/config) changes the network path, not the provider domain. - If diagnostics mention geo-blocking, captcha placeholders, or
NEED_CAPTCHA, try a user-owned provider relay for metadata calls. See Providers.
Failure classes
/diagnostics labels each attempt. The strings below are what the classifier writes into userSummary:
| Class | What you see | What to do |
|---|---|---|
| timeout | Provider is taking longer than expected | Wait, then /recover. fallback-first recovery auto-falls over after ~15s on a slow resolve |
| network | Provider had a network issue | Check connectivity; /recover |
| offline | Kunai cannot reach the network right now | Use /library if you have downloads; do not cycle providers |
| rate-limited | Provider is rate limiting requests | Wait, then /fallback |
| provider-empty | Provider did not return a playable stream | /fallback or another title |
| provider-parse | Provider returned data Kunai could not read | /recompute, then /fallback |
| expired-stream | Provider returned an expired stream | r / /recover |
| blocked | Provider appears blocked right now | User-owned metadata relay, or /fallback |
| sub-dub-mismatch | Does not match the selected sub/dub preference | Change language profile, then retry |
| title-episode-gap | Does not have this episode available yet | Wait for the episode, or another provider |
Empty search (not playback) with anime mode and AniDB often means curl is missing. kunai doctor reports it. Install curl, then search again; AniDB sits behind Cloudflare.
Evidence to collect
| Field | Where to find it |
|---|---|
| Provider id and failure class | /diagnostics → provider timeline |
| Fallback path (which provider recovered) | /diagnostics → provider timeline |
| Cache provenance (hit, stale, refetch) | /diagnostics → cache section |
| Structured trace | --debug-json or --debug-session output path |
| Title, mode, episode | Shell header or history entry |
Retry is not always an error
If Kunai is still cycling sources or retrying within one provider, the UI may show progress rather than a final failure. Wait for the timeline to complete before assuming total failure.
More: Providers, Supported and Unsupported.
Subtitles missing during playback
Symptoms: Video plays, no soft subs; diagnostics mentions Wyzie or late subtitle lookup.
What to try
- Press
sduring playback to reload subtitles (hotkey, not a slash command). - Open
/sourceor/tracksif inventory already lists another subtitle. - Late lookup uses Wyzie only when you set a Wyzie API key in Settings › Language. Kunai ships none. Without a key, lookup is skipped and a one-time notice explains why.
- Hardsub sources have burned-in text; switching tracks cannot remove them.
Playback started but died
Symptoms: mpv opens then exits; buffering never recovers; "stream expired" or IPC errors in diagnostics.
What to try
- Check mpv/player section in
/diagnosticsforexpired-stream,network-buffering,player-exited, or IPC failures. - Press
rto recover; Kunai may reload the URL or re-resolve depending on failure class. - If recovery loops, try
/fallbackfor a different provider. - Test mpv in isolation with
--mpv-clean --no-user-mpv-configto rule out local mpv.conf conflicts. - Enable in-process reconnect in Settings if network-read-dead stalls are common (
mpvInProcessStreamReconnect).
Evidence to collect
| Field | Where to find it |
|---|---|
| Player exit reason | /diagnostics → mpv/player |
| Stream health events | /diagnostics → cache / playback events |
| mpv log | --mpv-log-file /tmp/kunai-mpv.log |
| Whether cache was stale | /diagnostics → cache provenance |
| Subtitle attachment state | /diagnostics → subtitle evidence |
Network unavailable
Symptoms: Diagnostics shows offline or unreachable network; provider errors mention connectivity; downloads stall.
What to try
-
Confirm general connectivity outside Kunai (browser, ping).
-
Open
/diagnosticsand check the network snapshot. -
Do not assume every provider is down; Kunai avoids marking providers unhealthy from local network evidence alone.
-
Switch to offline library if you have completed downloads:
kunai --offline -
Retry online playback when connectivity returns; use
/recoverrather than restarting Kunai.
Evidence to collect
| Field | Where to find it |
|---|---|
| Network snapshot status | /diagnostics → network |
| Whether offline mode was active | Shell mode indicator |
| Download job errors | /downloads overlay |
| Timestamp of failure | --debug log in ./logs.txt |
Offline library does not auto-repair online
Opening /library or /offline never calls providers. Re-download and repair are explicit actions.
More: Downloads and offline.
Offline library issues
Symptoms: Completed download missing from library; playback fails for local file; artifact marked invalid; wrong duration or resume position.
What to try
- Open
/libraryor/offlineand check artifact status: ready, missing, or invalid. - Use reveal folder to confirm the file exists on disk.
- Run repair or re-download from the title group; Kunai uses saved download intent when available.
- Confirm
ffprobeis installed if duration metadata looks wrong (optional but helpful). - Verify free disk space meets
offlineFreeSpaceReserveBytesif new downloads fail.
Evidence to collect
| Field | Where to find it |
|---|---|
| Artifact validation result | /diagnostics → download/offline section |
| Local file size and duration | /library title details |
| Download job history | /downloads → failed/completed jobs |
downloadPath setting | /settings or config.json |
mpv missing or not found
Symptoms: Setup warns mpv is missing; playback never launches; diagnostics shows player unavailable.
What to try
# Debian/Ubuntu
sudo apt install mpv
# Fedora
sudo dnf install mpv
# Arch
sudo pacman -S mpvVerify: which mpv && mpv --version
After installing mpv:
- Run
kunai --setupagain to refresh capability detection. - Launch with
--debugand confirm mpv appears in startup capabilities. - Test a simple file:
mpv /path/to/local/file.mkvto isolate Kunai from player issues.
Evidence to collect
| Field | Where to find it |
|---|---|
| mpv detected at startup | /diagnostics → capabilities |
| PATH in terminal | which mpv output |
| Setup wizard result | kunai --setup transcript |
| mpv version | mpv --version first line |
More: Platforms, Getting started.
Share link or protocol handler issues
Symptoms: /watch says clipboard is empty or invalid; kunai --open fails to resolve; OS does not offer Kunai for kunai:// links.
What to try
- Copy a fresh link with
/sharefrom an active session; links needcat=orq=query params. - For clipboard open, run
/watchimmediately after copying (some terminals clear clipboard on focus change). - Trusted terminal launch:
kunai --open "kunai://play?..."works without OS registration. - Register handler once (Linux / WSL only):
kunai --install-protocol-handler, then retry from browser or chat app. macOS/Windows-native stay onkunai --open. - Handoff URLs from the OS may require confirmation; that is expected for untrusted surfaces.
More: Share links.
Installer and PATH issues
Symptoms: kunai: command not found; wrong binary runs; upgrade/uninstall refuses ownership; install fails checksum or 404; unsigned binary blocked or killed: 9 on Apple Silicon; rollback needed after a bad upgrade.
Just installed?
The installer writes your shell startup file, but it cannot change the
terminal that is already open. Open a new terminal, or run the source line
the installer printed. If you passed --skip-path-update, add the install
directory to PATH yourself.
What to try
-
List every
kunaion PATH (shadowing is the most common failure):# bash type -a kunai # or: which -a kunai # zsh whence -a kunai # or: which -a kunai / type -a kunai# Windows-native PowerShell Get-Command kunai -All -
Run read-only install health:
kunai doctor kunai doctor --jsonDoctor reports PATH winners, ownership/
install.json, version metadata, and remediations. It does not migrate or uninstall. -
Ownership mismatch: use the owner channel. Binary installs →
kunai upgrade/kunai uninstall. npm →npm uninstall -g @kitsunekode/kunaior ownership-awarekunai uninstall. Do not delete a package-manager install with a rawrmof another channel's launcher. -
Checksum / 404 on install or upgrade: confirm the release tag exists and both
SHA256SUMS.archives(downloaded archive) andSHA256SUMS(extracted binary) match. Retry withkunai install --forceor pin an explicit version (kunai install --force X.Y.Z/install.sh … --version X.Y.Z). HTTP 404/410 on an archive endpoint may select the older raw compatibility asset; checksum failures, malformed archives, timeouts, and 5xx responses fail closed instead. A persistent 404 usually means the asset for your target (for example musl vs glibc) is missing; check Platforms. -
Rollback to a previously verified local version (does not re-download):
kunai rollback --list kunai rollback kunai rollback --to <version> -
Unsigned binaries (beta):
-
macOS on Apple Silicon,
killed: 9: the binary is unsigned, and arm64 macOS refuses to execute it. There is no Gatekeeper dialog andxattrwill not fix it; quarantine is not what failed. Ad-hoc sign it:codesign --force --sign - ~/.local/bin/kunaiinstall.shdoes this for you; you only need it for a manual download. -
macOS Gatekeeper quarantine (Intel, or a binary downloaded outside the installer):
xattr -dr com.apple.quarantineon the install path. -
Windows SmartScreen:
Unblock-Fileonkunai.exe. -
Linux: verify the archive against
SHA256SUMS.archivesand the extracted binary againstSHA256SUMS.
Details: Unsigned binaries.
-
-
PATH shadowing: put the intended install directory first (
~/.local/binon Unix,%LOCALAPPDATA%\kunai\binon Windows). Remove or rename earlier shadowed copies. Re-check withtype -a/which -a(bash),whence -a(zsh), orGet-Command kunai -All(PowerShell), thenkunai doctor. -
Keep Windows-native and WSL installs separate; different PATH, mpv, and data roots. See Platforms.
Evidence to collect
| Field | Where to find it |
|---|---|
| PATH candidates / winner | kunai doctor or kunai doctor --json |
| Install channel / ownership | ~/.config/kunai/install.json (Windows: %APPDATA%\kunai\install.json) |
| Checksum / verification | doctor findings; GitHub Release SHA256SUMS.archives and SHA256SUMS |
| Rollback candidates | kunai rollback --list |
More: Install and update, Platforms.
Still stuck?
Binary installs: launch with --debug (writes ./logs.txt), reproduce, then /export-diagnostics. Open an issue via /report-issue after reviewing redaction.
Source-checkout traces (KUNAI_TRACE, bun run dev) live in Debugging workflow.
Last updated on
Runtime Feedback
Read Kunai's live playback health, memory, and network panels, and understand what each diagnostic signal is telling you while a session is still running.
Diagnostics and Reporting
Use Kunai diagnostics, support bundles, and traces to report a problem precisely, without leaking titles, queries, or anything else from your local machine.