Troubleshooting¶
Check daemon status and verify the vault before changing files. Keep the vault intact while you identify whether the failure concerns configuration, the daemon, source-file access, or stored content.
If a command prints a specific error, preserve it. CLI errors go to stderr and
return a non-zero status. HTTP errors include a machine-readable code.
The daemon will not start¶
Run it in the foreground to see the startup error directly:
Common causes:
config.tomlcontains an unknown key, invalid duration, or non-loopback bind address. The daemon rejects all three.- Another process owns the same vault. Check
docbank daemon status. Do not removevault.lockwhile a daemon may still be alive. - The configured port is already in use. Set
api_port = 0to let the OS choose one, or choose another fixed port.
Background daemon logs are JSON files under $DOCBANK_HOME/logs/. A data
command normally repairs stale runtime records and replaces an incompatible
daemon automatically. daemon status and daemon stop do not start a daemon.
A command cannot connect¶
Restart the daemon, then check whether it is running:
If restart fails, use foreground mode. If it succeeds but a raw HTTP client
still fails, confirm that the client uses the daemon's actual address and
effective API key. With api_port = 0 or an empty configured key, both change
when the daemon restarts. The docbank CLI discovers them automatically, but an
independent client does not.
For a stable integration, configure a fixed loopback port and API key as shown in the Agent integration guide.
Import completed with failures¶
docbank add continues past unreadable files inside a directory and reports
each failure. Its exit status is non-zero if any file failed, even when other
files were added successfully.
Fix the reported source permissions or availability problem, then repeat the command. Docbank skips matching content already imported under a destination name, so the completed files do not need another entry.
A missing or unreadable top-level argument is reported as a failed source, and the command continues with any remaining arguments. Docbank does not import non-regular files or file symlinks. Name the regular target file itself if it belongs in the vault. A source argument may be a symlink to a directory. Links inside that directory are still skipped and reported. See Importing documents.
Search cannot find document text¶
Search indexes live node names and current supported text contents. Remember that each term is a prefix match, and inspect the extractor job:
Body indexing currently requires verified UTF-8 text/*, JSON, or JSONL no
larger than 16 MiB. It is asynchronous and may take a few seconds after ingest
or replacement. PDF, office-document, OCR, invalid-UTF-8, NUL-containing, and
larger content is not indexed. Filename search still works. See
Searching for the full contract.
The running extractor keeps transient blob open, read, and verification failures queued and retries them. Repair or restore unavailable content, then retry search after the worker has completed a verified read.
A move or restore conflicts¶
The CLI never overwrites a live file. Moving onto an existing file returns
name already exists. Choose another destination, or move into an existing
directory to keep the source name.
Restore handles name reuse automatically by adding a numeric suffix. If its
original parent was permanently removed, it restores at /. Use the path
printed by docbank restore rather than assuming the old path returned.
HTTP clients must also distinguish:
409 existsorcycle: the requested tree state is invalid. Choose a new action.412 stale_revision: another mutation won. Re-read the node and reconsider the action before retrying.428 precondition_required: read the target node or tag again and send its current revision inIf-Match.
Verify reports a problem¶
verify classifies each affected hash:
| Result | Meaning | First response |
|---|---|---|
missing |
The catalog references bytes that cannot be found. | Stop maintenance and locate a known-good snapshot. |
corrupt |
Bytes are readable but no longer match their SHA-256 identity. | Preserve the vault and restore that content from a known-good copy. |
unreadable |
The storage layer returned an I/O or permission error. | Check mounts, permissions, and system logs before retrying. |
Do not run gc --run as a repair tool. GC removes unreachable data. It does
not repair referenced content. Preserve the affected vault, record the full
verify output, and restore from a snapshot only after identifying which copy
is known-good.
GC reclaimed fewer bytes than expected¶
A pack stores several blobs in one file that Docbank does not edit in place.
GC can remove the database references to an unused blob, but its bytes remain
inside the pack. docbank storage repack rewrites eligible packs with only
the content still needed and retires the old files.
Check pending_packed_bytes in the GC report. This counts packed bytes waiting
for repack, separately from individual files that GC can remove immediately.
See Trash, garbage collection, repack, and verify.
Update fails¶
docbank update requires a published release with a matching SHA-256 checksum.
It refuses unverifiable assets. If the install fails, it attempts to restart
the old daemon. Inspect docbank daemon status afterward and use daemon run
if the daemon is not healthy.
--force does not bypass checksum verification. It refreshes release metadata
and permits replacing an unversioned development build.
HTTP returns 401¶
Every /api/v1 request requires an effective API key, even when
api_key = "" in config. The empty setting means “generate a per-run key.”
Use exactly one of:
The health check, ping, interactive API docs, and OpenAPI documents do not
require authentication. A successful /health response shows that the server
is reachable. It does not check your key. See
HTTP API authentication for the request contract.
Before asking for help¶
Capture the version, daemon status, failing command or request, and relevant log lines. Remove API keys, shutdown tokens, document contents, and private paths before sharing them.