Pipeline Error Logging#

StandardPdfPipeline and ThreadedPipelineStage use two parallel error channels: Python's logging module for real-time visibility, and structured ErrorItem objects accumulated in ConversionResult.errors for post-conversion inspection. Understanding how these two channels work — and how they relate — is the key to monitoring, debugging, and handling page-level failures.

Logger name: All log records originate from a single module-level logger 1:

docling.pipeline.standard_pdf_pipeline

Attach a custom logging.Handler to this logger to intercept errors in real time.

Stage-Level Error Logging#

Each ThreadedPipelineStage worker thread catches exceptions in _process_batch() and emits a structured log record immediately:

• Model failure — _log.error("Stage %s failed for run %d: %s", ...) with exc_info=True 2. The full traceback is attached.
• Preprocess failure — same pattern but with the affected page numbers included and exc_info=False 3. Example output: ERROR docling.pipeline.standard_pdf_pipeline: Stage preprocess failed for run 1, pages [13]: std::bad_alloc
• Fatal stage error — top-level _run() guard calls _log.exception("Fatal error in stage %s", ...) for any exception that escapes the batch loop 4.
• Emit failure — _log.error("Output queue closed while emitting from %s", ...) when a downstream queue is closed early 5.
• Thread abandonment — _log.warning("Stage %s thread did not terminate within %.1fs ...") if stop() times out waiting for the worker 6.

Error Representation: ErrorItem#

Every caught exception is wrapped into an ErrorItem via the _make_error_item() helper 7:

FailureCategory values relevant to pipeline stages:

Error Flow: ThreadedItem → ProcessingResult → ConversionResult#

Errors travel through the pipeline in the ThreadedItem envelope alongside the page payload:

• is_failed: bool — set to True when an error occurs; downstream stages skip processing for failed items
• failure: ErrorItem | None — the structured error object for this page

The main thread drains the output queue and collects failed items into ProcessingResult.failed_pages. After all pages complete (or a timeout fires), _integrate_results() flushes errors into ConversionResult.errors and sets the final ConversionStatus:

• Every failure from failed_pages is appended to conv_res.errors 12
• Timeout adds an extra summary ErrorItem 13 and forces PARTIAL_SUCCESS
• Status: SUCCESS / PARTIAL_SUCCESS / FAILURE depending on success and failure counts 14

Producer and Timeout Warnings#

The PageProducer thread (which feeds pages into the first stage) has its own error path:

• Producer exception → _log.error("Producer failed for run %d: %s", ...) 15
• Document timeout → _log.warning(f"Document processing time ({elapsed_time:.3f}s) exceeded timeout ...") then adds run_id to timed_out_run_ids; in-flight stages skip remaining work for that run 16
• Producer thread abandonment → _log.warning(...) if the producer doesn't terminate within stage_shutdown_timeout_seconds 17

Debug Profiling Logs#

Stage timing is emitted at DEBUG level with a PIPELINE_PROFILING prefix, guarded by _log.isEnabledFor(logging.DEBUG) to avoid string formatting overhead 18. Example:

DEBUG docling.pipeline.standard_pdf_pipeline: PIPELINE_PROFILING Stage layout: run_id=3 pages=[1,2] start=1234.5 end=1235.1 duration=0.600s

Enable with logging.getLogger("docling.pipeline.standard_pdf_pipeline").setLevel(logging.DEBUG).

Key Source Files#