Skip to content

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.py
index 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.py
deleted file mode 100644
index 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.py
index 27d2da89a..6d3d303c9 100644
--- a/tests/unit/test_docling_service.py
+++ b/tests/unit/test_docling_service.py
@@ -10,6 +10,23 @@ import pytest
from 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.asyncio
async 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.py
index 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 coordinator
uses instead of the legacy in-method polling loop.
"""
-import pytest
from 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_cl
await 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.asyncio
async 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.py
index 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,