Troubleshoot txtop

Start with the in-app diagnostics. Use database commands when the problem persists or when preparing a bug report.

Inspect runtime state

Press D to open the diagnostics overlay. It shows refresh age, backfill progress, provider errors, projection and partial-read health, runtime-event logging, recent input, and the last debug-summary path.

Press y to write txtop-debug-summary-{epoch}.txt to the operating system’s temporary directory. It includes the same state plus longer input and scroll histories.

Check the database

txtop db doctor
txtop db doctor --deep

The deep check adds a full SQLite integrity check. Results use [ok], [warn], and [fail].

Other useful commands:

Command	Purpose
`txtop db check-invariants`	Validate consistency across tables
`txtop db backfill-status`	Show recent backfill operations
`txtop db events`	Query persisted runtime events
`txtop db repair`	Rebuild subscription rollups
`txtop ollama doctor`	Check the proxy and upstream Ollama

The default database is usage.db in txtop’s platform data directory. See the configuration reference for exact paths.

The command reference lists the supported database command families and their purpose.

Check API backfill

Enable backfill in the Config panel or config file:

openai_backfill_enabled = true
api_backfill_max_days = 7
show_backfill_debug_row = true

Inspect recent runs:

txtop db backfill-status
txtop db query backfill-runs --provider openai --last 10

Backfill cursors and run history persist across restarts.

Capture a debug bundle

txtop db debug-bundle --out ./txtop-debug.json

The bundle includes version and platform information, redacted config, database health, invariant failures, backfill history, table statistics, and recent persisted events.

Redaction is best effort. Review the file before sharing it; runtime errors can contain sensitive context.

A useful bug report includes:

The debug bundle
A debug summary written with y
Reproduction steps
A screenshot of the D overlay when relevant

Trace runtime events

Enable runtime_event_logging in the Config panel or config file; pass --log-file when launching txtop and select the event target with RUST_LOG:

RUST_LOG=txtop::runtime_event=debug txtop --log-file ./txtop.log

Console tracing goes to stderr. Structured TUI runtime events appear only in the configured log file.

Reset local state

Both commands ask for confirmation:

txtop db delete  # remove the local database
txtop db reset   # remove the local database and config

Use --yes only in scripts or after checking the resolved paths with each command’s --help output.