Troubleshooting
Find the responsible layer before changing or rerunning work
Start with the returned validation issue, diagnostic or error category and inspect the responsible resource. Do not rerun a writer merely because a query showed no rows.
| Symptom | Inspect | Next action |
|---|---|---|
| Unknown term | Compiled model and full IRI | Correct the identifier or declare/compile the term |
| Wrong model/version | Definition asset vs compiled package IDs | Select the actual compiled package and numeric version |
| No active binding | Binding status, package and root method | Validate/activate the intended binding |
| No records despite a graph | Actual source/store contents | Check a bounded source read or materializer readback |
| Wrong entity's value | Stable IDs and virtual identity fields | Fix identity join; do not rely on row position |
| Null asserted value | Predicate, subject, status, confidence and validity | Review eligibility; do not assume false |
| Ambiguous scalar | Cardinality and conflicting values | Resolve data/claim conflict or deliberately use Many |
| Forbidden or masked value | Caller permissions, role and term policies | Use authorized access; inspect dependency masks |
| Query not published/retired | Release status and selected version | Publish a reviewed draft or select eligible release |
| Changed query contract | Model hash, endpoint configuration, withdrawn bindings | Review dependencies and publish a compatible release |
| Queued response | Result job state | Continue execution using returned jobId |
| Expired or invalid cursor | Caller/input/release scope and expiry | Start a new execution; never fabricate a token |
| Partial result | Source/result bounds and diagnostics | Narrow the question or inspect source limitations |
| SPARQL disabled | Organization Consumer SPARQL mode | Ask the authorized owner to choose the intended mode |
| Extracted claim rejected | Real capture, selector/hash and completeness | Correct collection/selector evidence; do not invent IDs |
Runtime access
A plugin's credentials need access to the actual database/collection/remote target. User membership and query scope do not grant external-system privileges. Test reachability from the execution environment, not merely your laptop.
Partial writes
A failed pipeline can leave completed writes behind, depending on store atomicity. Inspect run effects and persisted output before retrying. Rollback of a model version, query retirement or cancellation does not reverse those writes.
Gather a useful report
Retain project/workspace, resource IDs, definition/package/query/pipeline versions, binding IDs, run/job ID, timestamps, diagnostics and a minimal reproducible fixture. Redact credentials. State whether the defect is in model validation, configuration, actual execution or readback; these are different checkpoints.
A query cannot execute
Publish a release, confirm access and binding targets, then validate input. Use the returned cursor/job continuation rather than changing offset mid-result. Expired results and changed releases can require a new execution.