OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
fix: Bad error message ingesting password protected PDF file (#2401)
Mike Pawlowski2cc36af51eef
diff --git a/src/services/docling_service.py b/src/services/docling_service.pyindex 88f92fa35..fd2106b07 100644--- a/src/services/docling_service.py+++ b/src/services/docling_service.py@@ -120,6 +120,51 @@ def _format_docling_error(payload: dict[str, Any]) -> str:return result+def _extract_document_json_content(payload: dict[str, Any], *, task_id: str) -> dict[str, Any]:+ """Return ``document.json_content`` from a ``/v1/result`` payload.++ docling-serve reports the *task* as ``success`` even when the *conversion*+ failed (e.g. a password-protected or corrupted PDF). The failure reason then+ lives in the result body's ``status`` / ``errors`` and ``json_content`` is+ null, so those are checked first — otherwise the real cause is discarded and+ every conversion failure reads as a malformed response.++ Raises:+ DoclingServeError: the conversion failed, or the payload carries no+ ``document.json_content``.+ """+ logger.debug("Extracting document from docling result", task_id=task_id)++ status = payload.get("status")+ if status == "failure" or payload.get("errors"):+ detail = _format_docling_error(payload)+ logger.warning(+ "Docling conversion failed",+ task_id=task_id,+ status=status,+ error=detail,+ )+ raise DoclingServeError(f"Docling processing failed: {detail}")++ document = payload.get("document")+ if not isinstance(document, dict):+ document = {}+ doc_content = document.get("json_content")+ if doc_content is None:+ logger.error(+ "Docling result missing document.json_content",+ task_id=task_id,+ status=status,+ document_keys=sorted(document) if isinstance(document, dict) else None,+ )+ raise DoclingServeError(+ f"docling-serve response missing document.json_content (status={status!r})"+ )++ logger.debug("Successfully extracted document from docling result", task_id=task_id)+ return doc_content++class DoclingService:_default_client: httpx.AsyncClient | None = None@@ -546,13 +591,7 @@ class DoclingService:except ValueError as e:raise DoclingServeError(f"Malformed docling result payload: {str(e)}") from e- if payload.get("status") == "failure" or payload.get("errors"):- raise DoclingServeError(f"Docling processing failed: {_format_docling_error(payload)}")-- document = payload.get("document") or {}- if document.get("json_content") is None:- raise DoclingServeError("docling-serve response missing document.json_content")- return document["json_content"]+ return _extract_document_json_content(payload, task_id=task_id)async def _poll_result(self,@@ -580,19 +619,16 @@ class DoclingService:status = status_data.get("task_status")if status == "success":+ logger.debug("Docling task succeeded; fetching result", task_id=task_id)result_response = await client.get(f"{self.docling_url}/v1/result/{task_id}", headers=headers)result_response.raise_for_status()result_json = result_response.json()- # Extract the json_content which matches the old convert_file/bytes return- document = result_json.get("document") or {}- doc_content = document.get("json_content")- if doc_content is None:- raise DoclingServeError("docling-serve response missing document.json_content")-- return doc_content+ # A "success" task status only means the job ran; the conversion+ # itself may still have failed, which the result body reports.+ return _extract_document_json_content(result_json, task_id=task_id)elif status == "failure" or status_data.get("errors"):raise DoclingServeError(f"Docling processing failed: {_format_docling_error(status_data)}"diff --git a/src/utils/docling_client.py b/src/utils/docling_client.pydeleted file mode 100644index 2f0ea88c7..000000000--- a/src/utils/docling_client.py+++ /dev/null@@ -1,88 +0,0 @@-"""Async HTTP client for docling-serve document conversion."""--import os-from pathlib import Path--import httpx--from utils.logging_config import get_logger--logger = get_logger(__name__)---class DoclingServeError(Exception):- """Raised when docling-serve conversion fails."""---async def _send_convert_request(- httpx_client: httpx.AsyncClient,- filename: str,- file_bytes: bytes,-) -> dict:- """Send a file to docling-serve and return the DoclingDocument dict."""- from api.docling import DOCLING_SERVICE_URL-- url = f"{DOCLING_SERVICE_URL}/v1/convert/file"-- ocr_engine = os.getenv("DOCLING_OCR_ENGINE")- data: dict[str, str] = {"to_formats": "json"}- if ocr_engine:- data["do_ocr"] = "true"- data["ocr_engine"] = ocr_engine- else:- data["do_ocr"] = "false"-- try:- response = await httpx_client.post(- url,- files={"files": (filename, file_bytes)},- data=data,- )- response.raise_for_status()- except httpx.ConnectError as exc:- raise DoclingServeError(- f"Cannot connect to docling-serve at {DOCLING_SERVICE_URL}. "- f"Is it running? Start with: uvx docling-serve run"- ) from exc- except httpx.TimeoutException as exc:- raise DoclingServeError(- f"Timeout converting document via docling-serve: {exc}"- ) from exc- except httpx.HTTPStatusError as exc:- raise DoclingServeError(- f"docling-serve returned HTTP {exc.response.status_code}: "- f"{exc.response.text[:500]}"- ) from exc-- resp_json = response.json()-- errors = resp_json.get("errors", [])- if errors:- raise DoclingServeError(f"docling-serve conversion errors: {errors}")-- doc_content = resp_json.get("document", {}).get("json_content")- if doc_content is None:- raise DoclingServeError(- "docling-serve response missing document.json_content"- )-- logger.info(- "Document converted via docling-serve",- filename=filename,- processing_time=resp_json.get("processing_time"),- )- return doc_content---async def convert_file(file_path: str, *, httpx_client: httpx.AsyncClient) -> dict:- """Convert a local file via docling-serve. Returns DoclingDocument dict."""- path = Path(file_path)- file_bytes = path.read_bytes()- return await _send_convert_request(httpx_client, path.name, file_bytes)---async def convert_bytes(- content: bytes, filename: str, *, httpx_client: httpx.AsyncClient-) -> dict:- """Convert in-memory bytes via docling-serve. Returns DoclingDocument dict."""- return await _send_convert_request(httpx_client, filename, content)diff --git a/tests/unit/test_docling_service.py b/tests/unit/test_docling_service.pyindex 27d2da89a..6d3d303c9 100644--- a/tests/unit/test_docling_service.py+++ b/tests/unit/test_docling_service.py@@ -10,6 +10,23 @@ import pytestfrom services.docling_service import DoclingServeError, DoclingService+# Shape of a /v1/result body for a password-protected PDF: the task ran to+# completion, but the conversion failed and no document was exported.+_PASSWORD_PROTECTED_RESULT = {+ "status": "failure",+ "errors": [+ {+ "component_type": "user_input",+ "module_name": "",+ "error_message": (+ "docling-parse could not load document abc123: "+ "Failed to load document (PDFium: Incorrect password error)."+ ),+ }+ ],+ "document": {"filename": "secret.pdf", "json_content": None},+}+def _make_response(status_code: int, json_data: dict = None) -> MagicMock:"""Create a mock HTTP response."""@@ -124,6 +141,30 @@ async def test_poll_result_missing_content(docling_service, mock_httpx_client):await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)+async def test_poll_result_surfaces_conversion_failure_from_result_payload(+ docling_service, mock_httpx_client+):+ """A 'success' task whose *conversion* failed reports the real cause.++ docling-serve marks the task successful once the job ran; a password-protected+ PDF then yields a result body with status="failure", an errors list and a null+ json_content. The errors must win over the generic "missing json_content".+ """+ mock_httpx_client.get.side_effect = [+ _make_response(200, {"task_status": "success"}),+ _make_response(200, _PASSWORD_PROTECTED_RESULT),+ ]++ with pytest.raises(DoclingServeError) as exc_info:+ await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)++ message = str(exc_info.value)+ assert message.startswith("Docling processing failed: ")+ assert "Incorrect password" in message+ assert "missing document.json_content" not in message++@pytest.mark.asyncioasync def test_poll_result_http_error(docling_service, mock_httpx_client):"""Propagates HTTP errors during polling as DoclingServeError."""diff --git a/tests/unit/test_docling_service_status_check.py b/tests/unit/test_docling_service_status_check.pyindex 98fea2c5a..ee926d5bb 100644--- a/tests/unit/test_docling_service_status_check.py+++ b/tests/unit/test_docling_service_status_check.py@@ -4,12 +4,14 @@ These are the single-poll primitives that the backend's polling coordinatoruses instead of the legacy in-method polling loop."""-import pytestfrom unittest.mock import AsyncMock, MagicMock+import httpx+import pytest+from services.docling_service import (- DoclingService,DoclingServeError,+ DoclingService,DoclingTaskState,)@@ -150,6 +152,36 @@ async def test_fetch_result_missing_json_content_raises(docling_service, mock_clawait docling_service.fetch_task_result("t1")+async def test_fetch_result_conversion_failure_raises_with_detail(docling_service, mock_client):+ """A failed conversion surfaces the docling error, not 'missing json_content'."""+ mock_client.get.return_value = _resp(+ 200,+ {+ "status": "failure",+ "errors": [+ {+ "component_type": "user_input",+ "module_name": "",+ "error_message": (+ "docling-parse could not load document abc123: "+ "Failed to load document (PDFium: Incorrect password error)."+ ),+ }+ ],+ "document": {"filename": "secret.pdf", "json_content": None},+ },+ )++ with pytest.raises(DoclingServeError) as exc_info:+ await docling_service.fetch_task_result("t1")++ message = str(exc_info.value)+ assert message.startswith("Docling processing failed: ")+ assert "Incorrect password" in message+ assert "missing document.json_content" not in message++@pytest.mark.asyncioasync def test_fetch_result_network_error_raises(docling_service, mock_client):mock_client.get.side_effect = httpx.ConnectError("dns error")diff --git a/tests/unit/test_task_service_get_task_status2.py b/tests/unit/test_task_service_get_task_status2.pyindex 8dd228896..5b4effb83 100644--- a/tests/unit/test_task_service_get_task_status2.py+++ b/tests/unit/test_task_service_get_task_status2.py@@ -149,6 +149,36 @@ class TestInferFailureMetadata:assert "docling-parse" not in msg.lower()assert "cbfc231c" not in msg+ def test_password_protected_pdf_non_langflow_path_maps_to_clean_message(self, task_service):+ """The non-Langflow path stores DoclingService's error verbatim.++ Unlike the Langflow path above there is no "did not complete" /+ "result unavailable" wrapper — the string is exactly what+ DoclingService._poll_result raises once the result body's errors are+ surfaced. It must map to the same user-facing password message.+ """+ ft = _make_file_task(+ phase=IngestionPhase.DOCLING,+ docling_status=DoclingPhaseStatus.PENDING,+ error=(+ "Docling processing failed: docling-parse could not load document "+ "cbfc231c73e85df69b34cfa56b4bb0696dc0f10d0536bcca821f92c324041bac: "+ "Failed to load document (PDFium: Incorrect password error)."+ ),+ )+ meta = task_service._infer_failure_metadata(ft)+ assert meta is not None+ assert meta["actionable_by"] == "USER_ACTIONABLE"+ assert meta["component"] == "docling"+ assert meta["failure_phase"] == "parsing"+ msg = meta["user_facing_message"]+ assert "password-protected" in msg.lower()+ assert "remove the password" in msg.lower()+ # no internals leaked+ assert "pdfium" not in msg.lower()+ assert "docling-parse" not in msg.lower()+ assert "cbfc231c" not in msg+def test_langflow_empty_content_not_retryable(self, task_service):ft = _make_file_task(phase=IngestionPhase.LANGFLOW,