Skip to content

Troubleshooting: Intake and Classification

This topic covers problems that occur during artifact ingest and automated classification.

Artifact ingest returns 409 Conflict

Symptom: POST /v1/artifacts returns 409 Conflict.

Cause: The source_ref field in the request body matches a source_ref that was already ingested. Raw to Knowledge enforces uniqueness on source_ref across all artifacts to prevent accidental duplicate processing.

Resolution: - If this is an accidental duplicate submission, no action is needed. The original artifact is unaffected. - If you intend to re-ingest the same source with updated content (e.g., a revised transcript), use a new source_ref value (e.g., append a version suffix: meeting-abc123-v2). - To check what was previously ingested, call GET /v1/artifacts and filter by source_ref.

Artifact ingest is blocked (status: BLOCKED)

Symptom: The artifact is created but shows status: BLOCKED and legal_basis: NOT_ASSESSED. No candidates are extracted.

Cause: The legal_basis field was submitted as NOT_ASSESSED or was not included in the request. Raw to Knowledge requires a declared legal basis before processing source content. This is an intentional compliance gate.

Resolution: - Re-submit the artifact with a valid legal_basis value (e.g., LEGITIMATE_INTEREST, CONTRACT, CONSENT). - The blocked artifact cannot be unblocked in place. Submit a new artifact with the correct legal_basis and a new source_ref. - If your organization has not determined the applicable legal basis, consult your data protection officer before processing.

No candidates extracted from a transcript

Symptom: POST /v1/artifacts/{id}/extract completes successfully, but GET /v1/artifacts/{id}/candidates returns an empty array.

Cause: One or more of the following: - The source text is too short or lacks interrogative structure (no question marks, no question-forming interrogatives like "what", "how", "why"). - The source_type field does not match the actual format of the content. For example, submitting a structured document with source_type: transcript may confuse the extraction parser. - The transcript contains only speaker turns without a clear question-and-answer structure.

Resolution: - Verify that source_type matches the actual format of the submitted content. - Check that the raw content contains identifiable questions. Try submitting a shorter excerpt known to contain clear Q&A turns. - For very short or fragmentary source content, extraction may legitimately produce no candidates. This is not an error.

Classification confidence is very low (below 0.5)

Symptom: ClassificationRecord.primary_confidence is below 0.5, and requires_review is always true.

Cause: The answer text is too short, ambiguous, or does not contain sufficient syntactic structure for the NLTK-based features to extract reliable signal. Very short answers (one or two words), highly informal language, or incomplete sentences all reduce classification accuracy.

Resolution: - Review the source answer text. If it is genuinely ambiguous or fragmentary, low confidence is the correct outcome — human review is appropriate. - Consider whether the source content can be enriched at ingest time. For example, including surrounding context from the transcript segment may help. - If your source material systematically produces short answers and low confidence, lower CLASSIFICATION_THRESHOLD to reduce the volume sent to review, accepting that some borderline classifications will be auto-assigned. - Manual Horn type assignment is available during the REVISED validation step if automated classification is consistently wrong for a specific type of content.

All answers are classified as OPEN_ISSUE

Symptom: Every candidate answer is classified with horn_type: OPEN_ISSUE, regardless of the content.

Cause: Two possible causes: 1. The source contains Flow B segments — questions without answers — which are expected to produce OPEN_ISSUE candidates until the generation pipeline supplies an answer. 2. Flow A vs. Flow B detection may have incorrectly assigned flow_type: FLOW_B to segments that do contain answers, causing those segments to produce generation work items instead of extractable candidates.

Resolution: - Check the flow_type on the TranscriptSegment records. If segments that visually contain answers are marked FLOW_B, this indicates a misclassification by the flow detector. - For Flow A content, verify that the transcript structure is recognizable — alternating speaker turns with clear question/answer pairing is best supported. - OPEN_ISSUE candidates from Flow B are expected. They should be escalated so the generation pipeline can produce a candidate answer.

requires_review is always true

Symptom: Every ClassificationRecord has requires_review: true, flooding the review queue with borderline cases.

Cause: The CLASSIFICATION_THRESHOLD environment variable defaults to 0.75. Any candidate with primary_confidence < 0.75 gets requires_review = true. If your content systematically produces confidences in the 0.5–0.74 range, every candidate will be flagged.

Resolution: - Assess whether the flagged candidates genuinely need review. If validators are consistently approving them without changes, the threshold may be too high for your content. - Lower CLASSIFICATION_THRESHOLD (e.g., to 0.60) to reduce the volume sent for human review. Set this in environment variables and restart the service. - Do not set the threshold below 0.50 — below that level, classifications are effectively random and should not be auto-assigned.

Grammar fields are null

Symptom: ClassificationRecord.assertion_grammar contains null values for subject, predicate, object_value, or all three.

Cause: The NLTK constituency parser could not extract a well-formed subject-predicate-object structure from the answer text. This is expected behavior for: - Short or elliptical answers (e.g., "Yes, three days.") - Informal or colloquial language - Answers consisting primarily of lists or bullet points - Non-English content

Resolution: - This is not an error. Grammar extraction is best-effort. Null grammar fields do not block validation or publication. - If structured grammar is required for your use case, it can be manually supplied during the REVISED validation step. The validator can set subject, predicate, object_value, and scope in the revision payload. - For a corpus where grammar extraction is systematically failing, consider pre-processing the source content to normalize sentence structure before ingest.