Represent traceable processing pipeline errors.
processing_errors allows failures to be audited without overloading
stage_runs. stage_runs.error_id points to the primary error for a failed or
blocked stage.
error_iderror_id is globally unique inside the processing registry.error_id is immutable after creation.processing_errors is owned by victus-processing.
CREATE TABLE processing_errors (
error_id TEXT PRIMARY KEY,
paper_id TEXT REFERENCES papers(paper_id),
pipeline_run_id TEXT REFERENCES pipeline_runs(pipeline_run_id),
stage_run_id TEXT REFERENCES stage_runs(stage_run_id),
error_type TEXT NOT NULL,
error_code TEXT,
message TEXT NOT NULL,
details_json JSONB,
retryable BOOLEAN NOT NULL DEFAULT false,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
| Field | Type | Description |
|---|---|---|
error_id |
TEXT | Primary identifier for the processing error. |
paper_id |
TEXT / NULL | Paper associated with the error when known. |
pipeline_run_id |
TEXT / NULL | Pipeline run associated with the error when known. |
stage_run_id |
TEXT / NULL | Stage run associated with the error when known. |
error_type |
TEXT | Stable error type classification. |
error_code |
TEXT / NULL | More specific machine-readable error code. |
message |
TEXT | Human-readable error message. |
details_json |
JSONB / NULL | Structured diagnostic details. |
retryable |
BOOLEAN | Whether retry may succeed without contract or data changes. |
created_at |
TIMESTAMPTZ | Error creation timestamp. |
processing_errors must:
retryableprocessing_errors must not store:
stage_runserror_id, error_type, message, retryable, and created_at arepaper_id, when present, must reference an existing papers.paper_id.pipeline_run_id, when present, must reference an existingpipeline_runs.pipeline_run_id.stage_run_id, when present, must reference an existingstage_runs.stage_run_id.error_type must be one of the allowed values.message must not be empty.details_json must be valid JSON when present.validation_errormodel_errorparser_errorstorage_errorschema_errortimeoutdependency_missingmanual_stopunknownCreated when a pipeline, stage, validation, storage, model, parser, dependency,
or manual-stop error is observed.
Errors are append-oriented and should not be materially rewritten.
Not deleted under normal operation.
Deprecated only by future contract version or error taxonomy migration.
ProcessingPapersPipelineRunsStageRunsNone.
processing_errors.paper_id -> papers.paper_idprocessing_errors.pipeline_run_id -> pipeline_runs.pipeline_run_idprocessing_errors.stage_run_id -> stage_runs.stage_run_idstage_runs.error_id -> processing_errors.error_idprocessing_errors records diagnostic detail. The authoritative stage state
remains in stage_runs.
Documentation clarification or validation wording refinement.
Backward-compatible additions such as nullable columns, new error types, or
additional diagnostic fields.
Breaking schema changes, identity changes, error type meaning changes, or field
removals.