Troubleshooting

Hansard separates provider sources, normalized archive files, derived viewer payloads, search indexes, and the background watcher. Diagnose the affected layer before choosing a repair.

Start with a health snapshot

Inspect the active archive and runtime.
Terminal window
```
hansard status
```
Run installation and source diagnostics.
Terminal window
```
hansard doctor
```
Check the watcher and search index separately.
Terminal window
```
hansard watcher status
hansard index status
```
Capture JSON when filing an issue or comparing two runs.
Terminal window
```
hansard status --json
hansard doctor --json
```

A source or conversation is missing

Confirm that the source is in the configured list, then preview a direct import:

hansard config sources list
hansard import --source cursor --since all --dry-run --explain-skips

If the dry run finds candidates, run the import without --dry-run. Add --json to inspect structured imported, skipped, and error results.

Check these source-specific boundaries:

claude-cloud is opt-in and never part of --source all. Run hansard import claude-cloud --since all explicitly.
ChatGPT and Claude.ai histories require downloaded web exports.
Windsurf protobuf-only rows remain repair stubs until a downloaded trajectory is imported, optionally with its claim token.
Modern Cursor transcripts and historical Cursor SQLite data have different coverage; a complete manual import is the recovery path for older history.
Aider histories are repository-local, so the repository containing .aider.chat.history.md must still be reachable.

When doctor reports an archived parser version older than the current importer, reimport that source with --since all. hansard rebuild does not rerun provider parsers.

The watcher is running but data is stale

Stream the watcher log while producing one new provider message:

hansard watcher logs --follow

Then test the same source directly:

hansard import --source cursor --since 30d --dry-run --explain-skips

If manual import works, recreate the background process and its filesystem watches:

hansard watcher restart

After changing the source list, a restart establishes event watchers for the new roots immediately. A repeated tick skipped: previous tick still running message means a previous pass is still active; inspect nearby log lines for the slow or failing source rather than assuming the process has stopped.

Search returns no results

Check whether the index is paused, then rebuild it:

hansard index status
hansard index resume
hansard index rebuild

Use --markdown-fallback only for legacy archives that lack canonical events:

hansard history "migration plan" --markdown-fallback

Search filters combine. Remove --repo, --provider, --tool, or --command one at a time when diagnosing an unexpectedly empty result. --no-web-chats intentionally excludes imported non-repository web conversations.

The viewer is stale or will not open

Refresh view payloads without reading provider sources:

hansard rebuild --since all

Open the browser viewer directly if native-app activation fails:

hansard app --no-fallback
hansard web --no-open

app --no-fallback reports a missing or unsupported native app instead of silently opening the browser fallback. The default browser viewer binds to 127.0.0.1:7824; choose another port when it is occupied:

hansard web --no-open --port 7825

Binding beyond loopback requires a password. A bare --host binds to all interfaces and is not appropriate without a deliberate network boundary:

HANSARD_WEB_PASSWORD='<strong-password>' \
  hansard web --host 0.0.0.0 --read-only

A web export will not import

Run hansard doctor and install unzip when ZIP support is missing, or pass an extracted folder.
Move the export into a terminal-readable local directory if access is denied.
For split ChatGPT privacy exports, pass the parent User Online Activity folder rather than one conversation part.
Supply --username for a new export account when it cannot be inferred.
Use hansard import chatgpt --instructions or hansard import claude-web --instructions to print the current walkthrough.

Original provider files are unavailable

Hansard may have preserved individual source files even after a provider rotated or deleted them. Preview safe restoration:

hansard restore-sources claude --dry-run

The command never overwrites existing files and never restores shared SQLite stores. Claude Code also has a dedicated preview:

hansard repair claude-code-backups --dry-run

After restoring source files, reimport the affected provider with --since all.

Optional system tools are missing

hansard doctor reports the relevant dependency and affected feature:

Tool	Impact when missing
`sqlite3`	Required for Codex, Devin, and Cursor SQLite stores.
`rg`	Recommended for fast recall and search.
`unzip`	Required to read ZIP web exports; extracted folders remain usable.

Last-resort refresh

When a package upgrade requires a clean local reimport, preview the update path:

hansard update --dry-run --since all

update clears local agent-session archive and derived import state before reimporting configured sources. Confirm that provider histories or restorable raw backups exist first. reset is broader and should be reserved for a fresh setup.