# Troubleshooting

> Fix missing conversations, late imports, empty search results, app launch problems, export imports, and stuck syncs.

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

1. In **Sessions**, select **Filter & sort**, then **Reset**.

2. Search for a distinctive phrase from the conversation.

3. 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.

4. 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.

5. Select **Incomplete runs** to see runs Hansard keeps out of the normal
   lists because they stopped before saving any messages.

## Start from the CLI

```sh
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:

```sh
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](https://www.hansard.dev/imports/web-exports/) and
  [Browser conversation capture](https://www.hansard.dev/imports/browser-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](https://www.hansard.dev/imports/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](https://www.hansard.dev/imports/supported-sources/) lists these
limits.

## Setup says there is not enough disk space

Preview the storage plan for the archive location you want:

```sh
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:

```sh
hansard watcher logs --follow
```

Then test the same source directly:

```sh
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:

```sh
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:

```sh
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:

```sh
hansard history "migration plan" --markdown-fallback
```

## The app shows stale data or will not open

Rebuild the conversation views without reading harness history:

```sh
hansard rebuild --since all
```

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

```sh
hansard app --no-fallback
hansard web
```

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

```sh
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:

```sh
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](https://www.hansard.dev/reference/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](https://www.hansard.dev/sync/personal-sync/).

## A release asks for a full reimport

Preview the refresh first:

```sh
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.

> **Reset is not a repair:** `hansard reset --yes` deletes the local archive and configuration. Try a
> source import, `hansard rebuild`, `hansard index rebuild`, a watcher restart,
> or `hansard update --dry-run` first.