Skip to content

Troubleshooting: Validation and Registry

This topic covers problems that occur during the human validation workflow and when publishing answers to the registry.

"ValidationStateError: Transition X → Y is not permitted"

Symptom: A validation action (approve, revise, reject, escalate) returns 422 Unprocessable Entity with the message ValidationStateError: Transition X → Y is not permitted.

Cause: The candidate is not in a state that allows the requested action. The most common cases: - Attempting to approve a candidate that has already been approved (state is APPROVED, not IN_REVIEW). - Attempting to claim a candidate that is already claimed by another validator (state is IN_REVIEW, not PENDING). - Attempting to reject a candidate that has already been rejected or escalated (terminal state).

Resolution: - Check the current state of the candidate: GET /v1/validation/candidates/{candidate_id}. - Refer to the permitted transitions table in States, Statuses, and Queues. - If the candidate is already IN_REVIEW by another validator, coordinate with that validator or have an administrator return the candidate to PENDING if the original claim is stale.

"Authority error: role X cannot approve Horn type Y"

Symptom: A validation action returns an error indicating the actor's role is not authorized to make decisions on this Horn type.

Cause: The Raw to Knowledge KGS authority table maps Horn information types to the validator roles that have approval rights for them. A validator with role content_author cannot approve a PRINCIPLE or REFERENCE answer that requires a subject_matter_expert role.

Resolution: - Identify the correct role for the Horn type being validated. Consult the authority table for your organization's KGS configuration. - Route the candidate to a validator with the appropriate role. Use the horn_type filter on GET /v1/validation/queue to ensure validators only see candidates within their authority. - If the role assignment in the system is incorrect, an administrator can update the actor's role assignment outside the API.

OPEN_ISSUE candidates cannot be approved

Symptom: Attempting to approve a candidate with horn_type: OPEN_ISSUE returns an error.

Cause: This is by design. OPEN_ISSUE is a placeholder type indicating that a question was identified but no answer was found in the source. There is no answer content to approve. Approving an OPEN_ISSUE would publish empty or invalid knowledge.

Resolution: - Escalate the OPEN_ISSUE candidate. This creates a WorkItem for the generation pipeline. - The generation pipeline will attempt to produce an answer using RAG and LLM. The generated candidate will be a new CandidateAnswer of a concrete Horn type (e.g., FACT, PROCEDURE). - Once the generated candidate passes validation, it will be published as an ApprovedAnswer of the appropriate type. The original OPEN_ISSUE candidate is resolved through the WorkItem lifecycle.

ConflictFlag blocks assignment to the validation queue

Symptom: A candidate or answer has a ConflictFlag and cannot progress through validation. Assignment is blocked.

Cause: Contradiction detection found two FACT-type answers with the same subject, predicate, and scope but different object_value. Raw to Knowledge raises a ConflictFlag and — when BLOCK_VALIDATION_ON_CONFLICT=true (the default) — prevents the conflicting answer from being assigned or approved.

Resolution: 1. Review both conflicting answers. Identify which is correct. 2. If the older answer is wrong: supersede it using POST /v1/registry/answers/{older_id}/supersede. The ConflictFlag is resolved automatically. 3. If the newer answer is wrong: dispute it using POST /v1/registry/answers/{newer_id}/dispute, then route it back through validation as REVISED or REJECTED. 4. If you need to disable conflict blocking while the review is in progress: set BLOCK_VALIDATION_ON_CONFLICT=false and restart the service. This permits conflicted answers to proceed but does not resolve the underlying conflict.

"ProvenanceError: missing fields"

Symptom: POST /v1/registry/answers returns 422 Unprocessable Entity with a ProvenanceError mentioning missing fields.

Cause: The registry publish request is missing one or more required provenance fields: - validation_record_id — must reference the ValidationRecord that authorized this publication. - owner_role — the role responsible for this answer's accuracy. - evidence_links — at least one URL or reference supporting the answer.

Resolution: - Check the request body against the schema in /docs. - Retrieve the validation_record_id from the candidate's validation history: GET /v1/validation/candidates/{candidate_id}/history. - Ensure owner_role and evidence_links are present and non-empty. An empty array for evidence_links is not accepted.

RegistryConflictRecord created on publish

Symptom: Publication succeeds (the answer appears in the registry), but a RegistryConflictRecord is created at the same time.

Cause: This is expected behavior, not an error. When an answer is published, the system checks for existing approved answers with the same subject+predicate+scope. If a conflicting answer is found, a RegistryConflictRecord is created to flag the conflict for review.

Resolution: - Check GET /v1/registry/conflicts for open conflict records. - Review both answers and decide which is correct. - Supersede the incorrect one, or dispute it if there is genuine uncertainty. - The conflict record is resolved when one of the conflicting answers is superseded, disputed, or retired.

"UnvalidatedRegistryWriteError"

Symptom: POST /v1/registry/answers returns 422 Unprocessable Entity with UnvalidatedRegistryWriteError.

Cause: The validation_record_id provided in the publish request exists, but the associated ValidationRecord does not have decision = APPROVED (or REVISED). The candidate may still be in IN_REVIEW, PENDING, or may have been REJECTED.

Resolution: - Retrieve the validation history for the candidate: GET /v1/validation/candidates/{candidate_id}/history. - Confirm the most recent ValidationRecord has decision: APPROVED or REVISED. - If the candidate is still in review, complete the validation step before publishing. - If the candidate was rejected, it cannot be published. A new extraction, generation, or manual submission is required.