Troubleshooting

Koda crashed — where do I find the diagnostic info?

When koda hits an unrecoverable error and exits, it leaves a forensic record in:

~/.config/koda/logs/panic.log

Each crash appends a delimited block:

======================================================================
[2026-04-29T20:55:32Z] PANIC
version:    koda 0.2.26
location:   koda-core/src/foo.rs:42:8
thread:     <unnamed>
message:    assertion failed: x > 0
backtrace:
  0: ...
  1: ...
======================================================================

The most recent panic is always at the bottom of the file.

Getting a useful backtrace

By default, the backtrace section will say:

backtrace:
  (disabled — re-run with RUST_BACKTRACE=1 to capture)

To capture a full backtrace, re-run koda with:

RUST_BACKTRACE=1 koda

Or for symbol resolution at every frame (slower startup, more verbose):

RUST_BACKTRACE=full koda

What to share when reporting a crash

When filing an issue at https://github.com/lijunzh/koda/issues, please include:

1. The most recent panic block from ~/.config/koda/logs/panic.log (with RUST_BACKTRACE=1 if possible)
2. The contents of ~/.config/koda/logs/latest (the per-process log for the crashed run — symlinks to the most recent koda-<pid>.log)
3. Your provider + model (e.g. gemini gemini-2.5-pro, anthropic claude-sonnet-4-5)

Log file rotation

Koda caps panic.log at 5 MB. When it exceeds that, it’s rotated:

• panic.log.3 — dropped (oldest)
• panic.log.2 → panic.log.3
• panic.log.1 → panic.log.2
• panic.log → panic.log.1
• panic.log → recreated empty on the next crash

Three generations are kept. If you want to archive a panic before rotation, copy panic.log.1 somewhere safe.

Koda’s terminal looks corrupted after a crash

Koda installs a panic hook that restores the terminal (disables raw mode, leaves the alternate screen, drops mouse capture) before the panic message prints. If you ever see a corrupted terminal after a crash, that’s a bug — please file an issue including the panic.log entry above so we can fix the affected code path.

A quick local recovery:

stty sane && tput cnorm && printf '\033[?1049l\033[?1000l\033[?1006l'

Where else does koda log?

Tracing verbosity is controlled by the RUST_LOG environment variable; the default is koda_core=info,koda_cli=info. Common debug recipes:

# More chatter from the inference loop
RUST_LOG=koda_core::session=debug koda

# Quiet everything but warnings
RUST_LOG=warn koda