docling-project / docling-project/docling-jobkit
Include failure reason for task status
- 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
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