Troubleshooting

Find the symptom below. Most fixes start by telling a hidden conversation from a missing one, so check the app first.

Start in the app

In Sessions, select Filter & sort, then Reset.
Search for a distinctive phrase from the conversation.
Set Source, Time, and Folder one at a time. If the conversation opens but looks incomplete, check its source and any field marked Not recorded. The harness did not store that data.
Open Settings → Imports. Check the Selection mode and the agents it follows, whether Background import is running, the Look-back window, and whether Pause search updates is on.
Select Incomplete runs to see runs Hansard keeps out of the normal lists because they stopped before saving any messages.

Start from the CLI

hansard status
hansard doctor
hansard watcher status
hansard index status

When you report a problem or compare two runs, capture hansard status --json and hansard doctor --json. Never attach real conversations or archive files to a public issue.

A conversation is missing

If Archive storage needs attention or Archive captures need retrying appears at the top of the app, open it to see failed captures and the last cleanup result. Free space or resolve the reported storage limit, then retry the affected import. A successful capture clears its failure record. hansard status --json and hansard doctor report the same failures. Storage accounting is recorded usage; these checks do not rescan the archive.

Confirm the source is configured, then preview an import and ask why sessions were skipped:

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

If the preview finds the session, run the same command without --dry-run. Add --json for structured results.

ChatGPT, Claude.ai, and Gemini history comes from downloaded exports or the browser extension. See Web exports and Browser conversation capture.
Aider history lives in each repository, so that repository must still exist on disk.
Windsurf conversations that show as repair placeholders need a downloaded trajectory. See Windsurf.
Older Cursor history needs a full import with --since all.
In the Mac app, history in Documents, Desktop, Downloads, a cloud storage folder, another app’s data, or an external or network drive imports only where macOS allows Hansard. Open Settings → Imports → macOS access and select Ask macOS. macOS never asks about Data from other apps, so its row offers Open System Settings, which opens Full Disk Access. Add or turn on Hansard there. A folder you declined offers the same button, which opens Files & Folders. The rows update when you switch back to Hansard, and the watcher reads with Full Disk Access after it next starts, such as when you log in or Hansard updates. An alert at the top of the window says when the watcher skipped such a folder.

If hansard doctor --deep reports an older parser version for a source, re-read it with hansard import --source <id> --since all or hansard rebuild --stale-parsers --provider <id>. A plain hansard rebuild does not rerun parsers.

A cloud source imports nothing

Cloud sources run when you name them or turn them on in Settings → Imports → Cloud agents, never as part of --source all. A source without its sign-in or key shows as not ready in Cloud agents; from the CLI it prints a setup note instead of failing.

Source	Command	Needs
Claude Code cloud and Remote Control	`hansard import claude-cloud --since all`	Your existing Claude Code sign-in
Claude Cowork cloud	`hansard import claude-cowork-cloud --since all`	Your existing Claude Code sign-in
Devin cloud	`hansard import devin-cloud --since all`	`DEVIN_API_KEY` or `devin.apiKey`
Jules	`hansard import jules --since all`	`JULES_API_KEY` or `jules.apiKey`
GitHub Copilot coding agent	`hansard import copilot-agent-cloud --since all`	`GH_TOKEN`, `GITHUB_TOKEN`, `copilot.token`, or a signed-in GitHub CLI
Cursor cloud agents	`hansard import cursor-cloud --since all`	`CURSOR_API_KEY` or `cursor.apiKey`
Factory cloud sessions	`hansard import factory-cloud --since all`	`FACTORY_API_KEY` or `factory.apiKey`, on an organization with the Sessions API enabled
Codex cloud tasks	`hansard import codex-cloud --since all`	Your saved Codex sign-in with ChatGPT, or the Codex CLI, installed and signed in

Some cloud sources return less than a full conversation. Codex cloud tasks read through the Codex CLI alone arrive as a status record and a diff, Cursor cloud agents have no model and keep tool calls only from the run streams Cursor still retains, and Jules sessions have no model or token usage. Each harness guide under Supported harnesses lists these limits.

Setup says there is not enough disk space

Preview the storage plan for the archive location you want:

hansard init --dry-run --data-dir /home/user/hansard-archive

The source size is the harness history already on this machine, not a download. Hansard also stores original copies, conversation files, and indexes, and keeps 2 GiB free as a reserve. Captured artifacts are not included in the estimate.

Choose a disk with more space, or run hansard init --skip-import to finish setup without importing. To see what older shared snapshots take up, run hansard prune archive-objects --dry-run.

New conversations appear late or not at all

Follow the watcher log while you send one message in the harness:

hansard watcher logs --follow

Then test the same source directly:

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

If the direct import works, restart the watcher so it watches the current source folders:

hansard watcher restart

A tick skipped: previous tick still running line means a watcher pass ran past more than one 30-second check, and the tick finished after line that follows says how many it skipped and names the pass’s three slowest steps. Look at nearby lines for the slow or failing source. hansard doctor reports the steps that took the most time in recent passes under watcher ticks.

If hansard status shows a watcher copy line, the watcher runs another copy of Hansard. New messages in conversations that a newer copy archived wait for that copy. Installing or updating the desktop app moves a watcher that runs an older release, such as a source checkout or an npm installation, to the app, and a watcher move line says what it did. To move it at another time, run hansard watcher adopt from the copy that should run it, or choose Use this version in Settings → Imports.

Search returns no results

Check whether indexing is paused, resume it, and rebuild the index:

hansard index status
hansard index resume
hansard index rebuild

Conversations imported while indexing was paused stay out of search until you resume indexing and rebuild the index.

Filters combine. Remove --repo, --provider, --tool, or --command one at a time to find the one that excludes the result. --no-web-chats hides imported web chats on purpose. For very old archives, try:

hansard history "migration plan" --markdown-fallback

The app shows stale data or will not open

Rebuild the conversation views without reading harness history:

hansard rebuild --since all

If the Mac app does not open, check whether it is installed, then use the browser instead:

hansard app --no-fallback
hansard web

hansard web uses port 7824. If another program holds that port, pick another:

hansard web --port 7825

A web export will not import

Hansard reads ZIP files itself. If the ZIP is damaged, extract it and pass the extracted folder instead.
If access is denied, move the export into a folder your terminal can read, such as ~/Downloads.
For a ChatGPT privacy export split into parts, pass the parent User Online Activity folder, not one part.
Pass --username when Hansard cannot tell which account a new export belongs to.
Print the current export steps with hansard import chatgpt --instructions or hansard import claude-web --instructions.

A harness deleted its history

Hansard keeps copies of the original files it imported. Preview putting them back:

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

Neither command overwrites existing files, and shared databases are never restored. After restoring, reimport that source with --since all. See Maintenance.

A required tool is missing

Tool	What it affects
`rg`	Recommended for fast search and recall.
`zstd`	Reads compressed Codex session files when Node.js has no built-in Zstandard support.

Hansard reads SQLite databases and ZIP exports with its own readers, so it needs neither sqlite3 nor unzip. hansard doctor lists each tool.

The first Personal Sync receive seems stuck

The first receive downloads another device’s complete archive and can take an hour or more. Check its progress with hansard personal-sync status. An interrupted receive continues where it stopped the next time sync runs. The watcher stops a pass only when its progress has not moved for 10 minutes, or after 24 hours, counting only time the computer is awake. A failed receive shows its error in hansard sync status and in Settings → Personal Sync. See Personal Sync.

A release asks for a full reimport

Preview the refresh first:

hansard update --dry-run --since all

update clears the local conversation archive before it reimports your sources. Confirm that the harness history, or Hansard’s preserved copies, still exist.