hSUM / docs 0.1.0-alpha.4 / troubleshooting

Troubleshooting

Start with hsum context and hsum doctor. Between them they explain most failures.

Read an error

hSUM errors name a cause, a fix, and a stable subcode:

problem: the selected hSUM index is unavailable
cause: no authorized managed index matches the selection
fix: run hsum context, then initialize or select the intended index
learn: hsum help error INDEX_NOT_FOUND — code: INDEX_NOT_FOUND — request: d4db1501-...

Every subcode has an offline explanation:

hsum help error INDEX_NOT_FOUND

INDEX_NOT_FOUND

The most common first-run failure. hSUM cannot find an index for the current selection. Causes, in order of likelihood:

You are not inside the indexed root. cd into it, or run hsum context to see what is selected.
You passed --data-dir or --cache-dir on one command but not the next. These must match across invocations.
HSUM_HOME differs between shells, so config resolves elsewhere.
No index exists yet — run hsum init ..

PIPELINE_FINGERPRINT after upgrading

The index was built by different indexing rules and cannot be read safely by this binary. Replace it explicitly:

hsum init --rebuild --dry-run
hsum init --rebuild

The dry run writes nothing. The rebuild replaces the trusted index and binding. Evidence and citations recorded before the pipeline change no longer resolve.

Search returns nothing

Confirm documents exist: hsum status reports active documents and passages.
Re-run hsum ingest if files changed. There is no watcher in alpha.4.
alpha.4 is lexical, not semantic. Search for identifiers and phrases that literally appear in the source; conceptual paraphrases will not match.
Check stop_reason in --json output to see whether retrieval was truncated.

Agent cannot see the server

Run hsum client doctor <CLIENT> — it validates the executable, binding, scope, framing, and runs a read-only probe.
Confirm the config uses an absolute path to the binary.
Confirm the binding UUID matches hsum context.
Regenerate the snippet with hsum client config <CLIENT> rather than hand-editing.

WRITER_LOCK

Another ingest holds the single-writer lock. Wait, or raise the ceiling:

hsum ingest --lock-timeout-ms 30000

Readers are never blocked, so search keeps working during an ingest.

Refused operations

hSUM refuses destructive or surprising actions until you confirm them explicitly:

Subcode	Confirm with
`BROAD_ROOT_CONFIRMATION_REQUIRED`	`hsum init --allow-broad-root`
`LARGE_SOURCE_CONFIRMATION_REQUIRED`	`hsum init --allow-large-source`
`EMPTY_SNAPSHOT_CONFIRMATION_REQUIRED`	`hsum ingest --allow-empty-snapshot`
`MASS_DELETE_CONFIRMATION_REQUIRED`	`hsum ingest --allow-mass-delete`
`TRUST_CONFIRMATION_REQUIRED`	`hsum trust <PATH> --confirm`

Read the message before confirming — each guards a real footgun.

Citation errors in the shell

Citations contain ? and #. Unquoted, your shell will mangle them into CITATION_MALFORMED. Always quote:

hsum get 'hsum://v1/...?rev=...#bytes=0-152'

Still stuck

Full error code index
Open an issue — include the request_id and hsum --version --verbose
Report a security issue privately