docling-project / docling-project/docling-jobkit

Include failure reason for task status

Open
#56 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
36
Forks
47
Avg merge
7d 3h
Merged PRs (30d)
17

Description

At https://github.com/docling-project/docling-jobkit/blob/73ef4cef275d2097b1f74bfbc84c9856449dd82a/docling_jobkit/orchestrators/local/worker.py#L124-L127, if an exception happens when processing a task, its status is set to `failure`, but the exception is just only logged and swallowed, so when using `docling-serve`, it's not easy to know what happened on client side, only way is to match by hand the `task_id` on the logs. That's not too much user friendly.

```python
ERROR:docling.datamodel.document:An unexpected error occurred while opening the document 1-COMUNICADO_5.pdf
Traceback (most recent call last):
File "/opt/app-root/lib64/python3.12/site-packages/docling/datamodel/document.py", line 150, in __init__
self._init_doc(backend, path_or_stream)
File "/opt/app-root/lib64/python3.12/site-packages/docling/datamodel/document.py", line 186, in _init_doc
self._backend = backend(self, path_or_stream=path_or_stream)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/app-root/lib64/python3.12/site-packages/docling/backend/docling_parse_v4_backend.py", line 135, in __init__
self._pdoc = pdfium.PdfDocument(self.path_or_stream)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/app-root/lib64/python3.12/site-packages/pypdfium2/_helpers/document.py", line 78, in __init__
self.raw, to_hold, to_close = _open_pdf(self._input, self._password, self._autoclose)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/opt/app-root/lib64/python3.12/site-packages/pypdfium2/_helpers/document.py", line 678, in _open_pdf
raise PdfiumError(f"Failed to load document (PDFium: {pdfium_i.ErrorToStr.get(err_code)}).")
pypdfium2._helpers.misc.PdfiumError: Failed to load document (PDFium: Incorrect password error).
ERROR:docling_jobkit.orchestrators.local.worker:Worker 0 failed to process job 1c355ffb-8814-4727-917e-67e29d9dca7a: Input document 1-COMUNICADO_5.pdf is not valid.
```

On client side, we only receive this:

```python
{'message': 'update', 'task': {'task_id': '1c355ffb-8814-4727-917e-67e29d9dca7a', 'task_status': 'failure', 'task_position': None, 'task_meta': None}, 'error': None}
```

I propose to add a `reason` argument to [`Task.set_status()`](https://github.com/docling-project/docling-jobkit/blob/73ef4ce/docling_jobkit/datamodel/task.py#L69-L80) that fills a `Task.task_status_reason` field. I think we could have available just only the exception message (`Input document 1-COMUNICADO_5.pdf is not valid`), for users that would be something helpful while preserving internal data, but if we can be able to provide the full exceptions chain (specially the `PdfiumError` error), that would be better, although it would require more changes.

After that, we would just need to get the `Task.task_status_reason` field on `docling-serve` code, and send it to the user. We can discuss that on its repository.

Contributor guide

Open the contributing guide

Research direction

Start with the exception handling in docling_jobkit/orchestrators/local/worker.py at lines 124-127 and Task.set_status() in docling_jobkit/datamodel/task.py at lines 69-80. Trace how task status updates reach docling-serve, then define and implement the failure reason flow so clients receive useful error information without losing the existing logging behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.