Troubleshooting

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.

For exportable evidence, run /export-diagnostics before closing the shell. See Diagnostics and reporting for privacy rules.

Quick triage

kunai --debug -S "Title"

/export-diagnostics
/report-issue

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

1. Open /diagnostics and read the provider attempt timeline.
2. Note the failure class (timeout, empty inventory, HTTP error, offline/network).
3. Press f or /fallback to try the next provider in your priority list.
4. If one provider always fails, check Customization for providerPriority / animeProviderPriority.
5. For domain drift, verify ~/.config/kunai/providers.json overrides are still valid.
6. If diagnostics mention geo-blocking, captcha placeholders, or NEED_CAPTCHA, try a user-owned provider relay for metadata calls. See Providers.

Evidence to collect

More: Providers, Supported and unsupported.

Playback started but died

Symptoms: mpv opens then exits; buffering never recovers; "stream expired" or IPC errors in diagnostics.

What to try

1. Check mpv/player section in /diagnostics for expired-stream, network-buffering, player-exited, or IPC failures.
2. Press r to recover — Kunai may reload the URL or re-resolve depending on failure class.
3. If recovery loops, try /fallback for a different provider.
4. Test mpv in isolation with --mpv-clean --no-user-mpv-config to rule out local mpv.conf conflicts.
5. Enable in-process reconnect in Settings if network-read-dead stalls are common (mpvInProcessStreamReconnect).

Evidence to collect

Network unavailable

Symptoms: Diagnostics shows offline or unreachable network; provider errors mention connectivity; downloads stall.

What to try

1. Confirm general connectivity outside Kunai (browser, ping).

2. Open /diagnostics and check the network snapshot.

3. Do not assume every provider is down — Kunai avoids marking providers unhealthy from local network evidence alone.

4. Switch to offline library if you have completed downloads:

   kunai --offline

5. Retry online playback when connectivity returns — use /recover rather than restarting Kunai.

Evidence to collect

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

1. Open /library or /offline and check artifact status: ready, missing, or invalid.
2. Use reveal folder to confirm the file exists on disk.
3. Run repair or re-download from the title group — Kunai uses saved download intent when available.
4. Confirm ffprobe is installed if duration metadata looks wrong (optional but helpful).
5. Verify free disk space meets offlineFreeSpaceReserveBytes if new downloads fail.

Evidence to collect

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 mpv

brew install mpv
which mpv && mpv --version

After installing mpv:

1. Run kunai --setup again to refresh capability detection.
2. Launch with --debug and confirm mpv appears in startup capabilities.
3. Test a simple file: mpv /path/to/local/file.mkv to isolate Kunai from player issues.

Evidence to collect

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

1. Copy a fresh link with /share from an active session — links need cat= or q= query params.
2. For clipboard open, run /watch immediately after copying (some terminals clear clipboard on focus change).
3. Trusted terminal launch: kunai --open "kunai://play?..." works without OS registration.
4. Register handler once (Linux / WSL only): kunai --install-protocol-handler, then retry from browser or chat app. macOS/Windows-native stay on kunai --open.
5. 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; rollback needed after a bad upgrade.

What to try

1. List every kunai on 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

2. Run read-only install health:

   kunai doctor
   kunai doctor --json

   Doctor reports PATH winners, ownership/install.json, version metadata, and remediations. It does not migrate or uninstall.

3. Ownership mismatch: use the owner channel. Binary installs → kunai upgrade / kunai uninstall. npm → npm uninstall -g @kitsunekode/kunai or ownership-aware kunai uninstall. Do not delete a package-manager install with a raw rm of another channel's launcher.

4. Checksum / 404 on install or upgrade: confirm the release tag exists and SHA256SUMS matches. Retry with kunai install --force or pin an explicit version (kunai install --force X.Y.Z / install.sh … --version X.Y.Z). A 404 usually means the asset for your target (for example musl vs glibc) is missing — check Platforms.

5. Rollback to a previously verified local version (does not re-download):

   kunai rollback --list
   kunai rollback
   kunai rollback --to <version>

6. Unsigned binaries (beta): Windows SmartScreen → Unblock-File on kunai.exe; macOS Gatekeeper → xattr -dr com.apple.quarantine on the install path; Linux → verify against SHA256SUMS. Details: Unsigned binaries.

7. PATH shadowing: put the intended install directory first (~/.local/bin on Unix, %LOCALAPPDATA%\kunai\bin on Windows). Remove or rename earlier shadowed copies. Re-check with type -a / which -a (bash), whence -a (zsh), or Get-Command kunai -All (PowerShell), then kunai doctor.

8. Keep Windows-native and WSL installs separate — different PATH, mpv, and data roots. See Platforms.

Evidence to collect

More: Install and update, Platforms.

Still stuck?

KUNAI_TRACE=provider,playback,cache bun run dev -- -S "Title" --debug-session

For everyone else:

1. Export diagnostics before exit: /export-diagnostics
2. Open an issue via /report-issue with the bundle attached (after reviewing redaction).
3. Include the symptom section you followed and what you already tried from this page.