opendataloader-project/opendataloader-pdf · error · IOException

Docling Fast Server processing failed: %s

Error message

Docling Fast Server processing failed: %s

What it means

The response JSON contained "status":"failure", meaning the docling-fast-server accepted the PDF but the conversion pipeline itself reported failure. The errors node (if present) is stringified into the message so the caller sees which pages/steps failed. This is a backend processing failure, not a transport error.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java:210

            throw new IOException("Docling Fast Server request failed with status " + response.code() +
                ": " + bodyStr);
        }

        ResponseBody body = response.body();
        if (body == null) {
            throw new IOException("Empty response body");
        }

        String responseStr = body.string();
        JsonNode root = objectMapper.readTree(responseStr);

        // Check for API error status
        JsonNode statusNode = root.get("status");
        String status = statusNode != null ? statusNode.asText() : "";
        if ("failure".equals(status)) {
            JsonNode errorsNode = root.get("errors");
            String errorMessage = errorsNode != null ? errorsNode.toString() : "Unknown error";
            throw new IOException("Docling Fast Server processing failed: " + errorMessage);
        }

        // Log partial_success status
        if ("partial_success".equals(status)) {
            JsonNode errorsNode = root.get("errors");
            LOGGER.log(Level.WARNING, "Backend returned partial_success: {0}",
                errorsNode != null ? errorsNode.toString() : "no error details");
        }

        // Extract document content
        JsonNode documentNode = root.get("document");
        if (documentNode == null) {
            throw new IOException("Invalid response: missing 'document' field");
        }

        JsonNode jsonContent = documentNode.get("json_content");

        // Extract per-page content from json_content if available

View on GitHub (pinned to a7789b8e77)

Solutions

1. Read the errors fragment in the message to find the failing page/step
2. Decrypt the PDF (remove password) before sending if it is encrypted
3. Retry with a smaller page range to isolate the failing page
4. Check server logs and restart the backend if its model crashed
5. Fall back to Java-only processing for this document

try {
    return client.convert(request);
} catch (IOException e) {
    if (e.getMessage().startsWith("Docling Fast Server processing failed")) {
        // backend rejected the doc — fall back to Java pipeline
        log.warn("backend failed, using Java-only: {}", e.getMessage());
        return null; // signal caller to use Java extraction
    }
    throw e;
}

When it happens

Trigger: parseResponse reads root.get("status").asText() == "failure"; the message includes root.get("errors").toString() (or 'Unknown error' if absent).

Common situations: Corrupt or encrypted PDF the backend cannot parse; backend model error on a specific page; backend dependency (OCR/table model) missing or crashed; out-of-memory on a very large document.

Related errors

• Empty response body
• Invalid response: missing 'document' field
• Hybrid server is not available at %s To start the local hybr
• Hybrid server at %s returned HTTP %s during health check. Th
• Failed to convert

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/52151fcec300f8e6. Report an issue: GitHub.