Troubleshooting
metawarc renders expected domain failures as concise CLI errors instead of raw
Python tracebacks. Use metawarc doctor --dbfile collection.db as the first
diagnostic for workspace problems.
Common issues
Missing optional extra
Error:
API/replay support requires `pip install metawarc[api]` or `metawarc[replay]`
MCP support requires `pip install metawarc[mcp]`
Fix: install the extra listed in Installation.
Core indexing and querying do not need api or mcp.
metawarc search returns no matches
The workspace has not populated the texts sidecar, or the phrase did not
match. Run metawarc index-content --text once and try again. The command
prints (no matches) and exits 0 — it does not raise — when the sidecar is
empty or the phrase is not present.
Batch job stays pending
metawarc jobs submit writes the file immediately; the runner is the
asyncio Task started by metawarc serve's lifespan handler. Make sure
metawarc serve is running on the same workspace, then re-check
metawarc jobs list --status pending.
Unsupported or unrecognized schema
A 2.0 workspace uses schema version 2. Newer schemas fail closed. Legacy 1.2/1.3
files/tables catalogs are detected on write: a .legacy.bak copy is made
and paths are imported when the layout is unambiguous. If migration cannot
proceed safely, doctor reports rebuild guidance instead of rewriting source
archives.
metawarc doctor --dbfile collection.db
Moved WARC source
Archive identity is stable. Metawarc never silently guesses that a new path is the same file. Rebind explicitly after independent verification:
metawarc rebind ARCHIVE_ID /new/path/site.warc.gz --dbfile collection.db
Use --force only after you have confirmed the fingerprint mismatch is expected.
Non-loopback bind rejected
REST and MCP bind to loopback by default. Non-loopback REST requires
METAWARC_API_TOKEN / --token or --allow-insecure. Non-loopback MCP
requires --allow-insecure.
METAWARC_API_TOKEN='replace-me' metawarc serve --dbfile collection.db --host 0.0.0.0
--unsafe-where is local CLI only
Raw SQL is available only on trusted local list-files and dump. REST and MCP
reject it. Never pass untrusted text to --unsafe-where.
Export refused overwrite or path traversal
dump and get sanitize record IDs, write below the requested directory, and
refuse silent overwrite. Choose a new --output path or remove the existing
files after you have verified they are disposable.
Doctor reports errors
metawarc doctor --dbfile collection.db
metawarc doctor --dbfile collection.db --repair # dry-run repair plan
metawarc doctor --dbfile collection.db --repair --apply # apply planned repairs
--apply requires --repair. Mutating recovery operations preview by default.
Cleanup candidates
metawarc cleanup --dbfile collection.db # preview
metawarc cleanup --dbfile collection.db --apply # remove previewed files