Differentiate between conversion whre `document_timeout` is reached versus those for which individual pages failed

[simonschoe]

Bug

Previously, ConversionStatus.PARTIAL_SUCCESS was only emitted when document_timeout is reached. Since #2939 was merged, ConversionStatus.PARTIAL_SUCCESS is also assigned when individual pages fail.

As a result, a downstream consumer has no way, based on the conversion results, to differentiate between a document for which only individual pages failed (which might be okay) versus a document for which the timeout was reached and where the last X pages are missing (which might be handled differently).

Docling version

docling                                      2.82.0
docling-core                                 2.70.2
docling-ibm-models                           3.13.0
docling-parse                                5.6.1

[dosubot]

Currently, you can differentiate between timeout and individual page failures by inspecting the conv_res.errors list. When a timeout occurs, failed pages are marked with the error message "document timeout exceeded", while individual page failures contain different error messages like "Page {page_no} failed to parse" or the specific exception.

As a workaround:

def is_timeout_scenario(conv_res: ConversionResult) -> bool:
    timeout_errors = [e for e in conv_res.errors 
                     if "timeout exceeded" in e.error_message.lower()]
    return len(timeout_errors) > 0

That said, this is a valid feature request—having a first-class way to distinguish these scenarios (e.g., a dedicated status like TIMEOUT or a flag on the result) would be cleaner than parsing error messages.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[simonschoe]

Unfortunately, this does not work. When the document_timeout is reached, conv_res.errors is effectively empty.

I guess because of:

# In _build_document:
if elapsed_time > self.pipeline_options.document_timeout:
    _log.warning(...)
    timeout_exceeded = True
    ctx.timed_out_run_ids.add(run_id)
    if not input_queue_closed:
        ctx.first_stage.input_queue.close()
        input_queue_closed = True
    # Break immediately - don't wait for in-flight work
    break

The way I understand it, when the timeout hits, some fed pages are still in-flight → lost (not counted anywhere). Seems to me like a bug since the lost in-flight pages get silently dropped from conv_res.pages, and their errors are never recorded.