Errors and current limitations
Separate a normal resolver outcome from a process-level failure.
Structured query outcomes
Section titled “Structured query outcomes”| Status | Meaning | Recovery |
|---|---|---|
ok |
A result or candidate-bearing result was constructed. | Inspect warnings, references, classification, and confidence. |
not_found |
No matching parsed fact was found. | Check the identifier, edition, loaded parts, and context; use cited text when appropriate. |
validation_error |
Input validation failed. | Correct the tag, UID, VR, or other identifier. |
These statuses are returned inside the response envelope.
Common operational failures
Section titled “Common operational failures”| Failure | Likely cause | Recovery |
|---|---|---|
| SQLite KB does not exist | No build at the conventional path or wrong --db. |
Build the fixture or official edition; pass the matching absolute database path. |
| Source manifest does not exist | fetch or local registration has not run for the edition/cache. |
Acquire or register artifacts first. |
| Manifest checksum mismatch | Manifest content changed after its digest was written. | Restore the manifest or reacquire with an intentional --force, then rebuild. |
| Artifact checksum mismatch | A cached source file changed. | Investigate, reacquire, rewrite the manifest intentionally, and rebuild. |
| Database metadata mismatch | Database and manifest come from different source states or editions. | Select matching files or rebuild SQLite from the verified manifest. |
| Artifact or database already exists | Overwrite protection is active. | Choose a new path or use --force only after confirming replacement is intended. |
| Unsupported backend | --backend is not sqlite. |
Use SQLite; no other backend is implemented. |
| Missing MCP dependency | Environment lacks the optional mcp extra. |
Install with uv sync --extra mcp or equivalent. |
| Official edition discovery fails | Network failure, changed listing, no unique current edition, or historical label absent from archive. | Check connectivity and official metadata; use a verified concrete edition or local registration. |
| Quality gate fails | A configured warning or unresolved-reference threshold was exceeded. | Inspect the completed summary; fix parsing or establish a justified baseline. |
| External agent run fails | Timeout, nonzero command, invalid JSON, or wrong run schema. | Test the adapter independently and inspect stderr/transcript diagnostics. |
| Config rejected | Invalid YAML, unknown field, nonlocal SQLite URL, invalid range, or citations disabled. | Correct the profile using the configuration reference. |
Synthetic fixture availability
Section titled “Synthetic fixture availability”build-fixture locates fixture files under the source repository’s
tests/fixtures_synthetic directory. Run the fixture walkthrough from a source
checkout. A standalone installed command may not include repository test
fixtures.
Partial builds
Section titled “Partial builds”A database built from selected parts is valid for those loaded artifacts but can be incomplete for cross-part queries. Examples:
- SOP Class context needs PS3.4 and linked PS3.3 records;
- a contextual attribute result also needs PS3.6 identity;
- Transfer Syntax enrichment needs PS3.5 and PS3.6;
- DICOMweb media relationships need the relevant PS3.18 and media records.
A not_found result from a partial build is not proof that the standard lacks
the fact.
Ambiguity and null fields
Section titled “Ambiguity and null fields”The resolver deliberately returns candidates, warnings, or null fields when one deterministic answer is unavailable. This commonly affects:
- names reused across contexts;
- route templates with multiple possible transactions;
- value terms linked to multiple attribute uses;
- conditional effective types;
- incomplete cross-references;
- parser structures that do not match the expected shape.
Do not replace these outcomes with fuzzy matching in downstream code without marking the result as separate heuristic behavior.
Destructive --force
Section titled “Destructive --force”Depending on the command, --force can replace:
- cached artifacts;
- a source manifest;
- a generated SQLite database.
After changing source artifacts or a manifest, rebuild the database and rerun
verification. Never use --force merely to hide a provenance mismatch.
Current nonfeatures
Section titled “Current nonfeatures”The documented source state does not implement:
- an HTTP API;
- a network MCP transport;
- a PostgreSQL backend;
- vector search;
- a hosted public query service;
- a prebuilt official-edition database download;
- a full-standard JSON or text export;
- bulk PS3.16 terminology export;
- official DICOM conformance certification;
- MCP resources or prompts;
- write-capable MCP query tools.
The repository Makefile’s run-api target explicitly reports that the HTTP API
is not implemented.
Coverage limitations
Section titled “Coverage limitations”Named standard parts are not necessarily semantically parsed in full. Use the coverage matrix, build warnings, official integration tests, and returned references to assess the exact local build.