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.
Diagnostics are local-first. Kunai records enough runtime context to explain failures without automatically uploading anything. You choose when to export or share evidence.
Quick reference
| Command / flag | Purpose |
|---|---|
/diagnostics | Runtime panel: provider timeline, cache, mpv, network |
/export-diagnostics | Redacted JSON bundle near cwd |
/report-issue | GitHub issue flow with bundle guidance |
--debug | Verbose logging to ./logs.txt |
--debug-json | Structured JSONL event stream |
--debug-session | Full session trace with path printed on stderr |
Launch example:
kunai --debug -S "Title"--debug writes verbose redacted logs to ./logs.txt in the working directory. Source-checkout traces (KUNAI_TRACE, bun run dev -- --debug-json) live in Debugging workflow.
Opening the diagnostics panel
Press / and choose diagnostics, or type:
/diagnosticsThe panel typically includes:
- Capabilities: mpv, yt-dlp, ffprobe, curl, poster renderer detection at startup
- Provider: resolve stages, failure classes, fallback timeline
- Cache: hit/miss, stale revalidation, stream health events
- Subtitles: attachment evidence and active track
- Playback / mpv: player state, IPC events, exit reasons
- Network: connectivity snapshot (does not mark providers unhealthy alone)
- Presence: Discord connect/clear status
- Download / offline: queue failures, artifact validation
- Updates: background check results
Provider attempts in progress show as retry/fallback progress, not always final errors.
Exporting a support bundle
/export-diagnosticsThe bundle is redacted by design. It should include:
- Runtime metadata and version
- Capability detection results
- Provider attempt timeline (ids and failure classes, not URLs)
- Cache provenance summaries
- Player failure classifications
- Recent diagnostic events by category
It must not include:
- Raw stream URLs or signed query parameters
- Cookies, authorization headers, or session tokens (including YouTube
cookiesFromBrowser/cookiesFilematerial) - Private home-directory paths (redacted to placeholders)
Review before sharing
Open the exported JSON locally before attaching to a public issue or chat. If something sensitive slipped through, redact it manually and note the omission in your report. Never paste cookie file contents into the issue body; point to a redacted bundle path only.
Reporting an issue
/report-issueThe flow should:
- Preview what will be included
- Ask for confirmation
- Write a redacted diagnostics bundle
- Open the GitHub issue page with a safe prefilled summary
If browser open fails, Kunai shows the issue URL and local bundle path.
For developers contributing fixes, also see Contribute.
Structured traces
Scoped JSON traces (KUNAI_TRACE, --debug-json, --debug-session) are for source checkouts. See Debugging workflow.
--debug on an installed binary is enough for most bug reports (./logs.txt plus /export-diagnostics).
Recovery mode vs slow resolve
Default recovery is guided. In Settings you can set recoveryMode to fallback-first: after a slow primary resolve (~15 seconds) Kunai auto-falls over to the next compatible provider instead of waiting on you. manual never auto-falls over.
Developers: Debugging workflow.
What diagnostics cover (by category)
Startup capabilities
Recorded once per session:
- mpv found on PATH
- yt-dlp / ffprobe availability
- curl availability (used by the anime providers, which sit behind Cloudflare)
- Terminal poster support (Kitty / iTerm2 inline / Sixel / half-block)
- Platform opener availability
Missing optional tools degrade gracefully; setup explains gaps.
Provider resolve
- Which provider was tried and in what order
- Provider-local retry cycles (sources/variants)
- Global fallback transitions
- Failure class per attempt (timeout, empty, HTTP, offline)
See Providers.
Playback and mpv
- Launch parameters classification (not raw URLs)
- IPC command outcomes
expired-stream,network-buffering,player-exitedevents- In-process reconnect attempts when enabled
Cache and stream health
- Cache hit vs cold resolve
- Revalidation after health failure
- Whether stale cache was kept when fresh lookup failed but old stream still playable
Presence
- Discord connect/disconnect/clear outcomes
- Privacy mode in effect
- Unavailability reasons (missing client id, IPC unreachable)
Configure presence in /settings; see Customization.
Downloads and offline
- Job state transitions (queued, running, failed, completed)
- Artifact validation results (size, ffprobe duration)
- Offline library source selection (local-only path)
Good smoke tests
From an installed kunai binary:
kunai -S "Dune"
kunai -a -S "Attack on Titan"
kunai --debug -S "Dune"
kunai --discover
kunai --random
kunai --calendar
kunai --offline
kunai --zen --offlineSource-checkout equivalents live in Debugging workflow.
After each run, spot-check /diagnostics or export a bundle if something looked wrong.
Privacy and reliability expectations
Diagnostics stay on disk until you export them. Kunai does not phone home with traces.
Support bundles align with Reliability and privacy:
- Durable user data (history, lists, downloads) is never deleted by cache maintenance
- Cache rows are disposable and may be pruned at startup
- Provider health is not poisoned by local network outages alone
When to use which tool
| Situation | Tool |
|---|---|
| Quick state while in app | /diagnostics |
| Shareable artifact for a bug | /export-diagnostics |
| Compare two runs programmatically | --debug-json or --debug-session |
| GitHub issue with guidance | /report-issue |
| Verbose text log | --debug → ./logs.txt |
Symptom index: Troubleshooting.
Last updated on
Troubleshooting
A symptom-first index for Kunai: provider failures, playback crashes, network problems, setup errors, and poster issues, each with concrete fix steps.
Reliability and Privacy
What Kunai stores locally, what it never sends, how it limits third-party traffic, and how diagnostics stay redacted by default when you report a failure.