{"record":{"id":"57eefe4620dd1c34","repo":"opendataloader-project/opendataloader-pdf","slug":"docling-fast-server-request-failed-with-status-s","errorCode":null,"errorMessage":"Docling Fast Server request failed with status %s: %s","messagePattern":"Docling Fast Server request failed with status (.+?): (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java","lineNumber":192,"sourceCode":"            int minPage = request.getPageNumbers().stream().min(Integer::compareTo).orElse(1);\n            int maxPage = request.getPageNumbers().stream().max(Integer::compareTo).orElse(Integer.MAX_VALUE);\n            bodyBuilder.addFormDataPart(\"page_ranges\", minPage + \"-\" + maxPage);\n        }\n\n        return new Request.Builder()\n            .url(baseUrl + CONVERT_ENDPOINT)\n            .post(bodyBuilder.build())\n            .build();\n    }\n\n    /**\n     * Parses the HTTP response into a HybridResponse.\n     */\n    private HybridResponse parseResponse(Response response) throws IOException {\n        if (!response.isSuccessful()) {\n            ResponseBody body = response.body();\n            String bodyStr = body != null ? body.string() : \"\";\n            throw new IOException(\"Docling Fast Server request failed with status \" + response.code() +\n                \": \" + bodyStr);\n        }\n\n        ResponseBody body = response.body();\n        if (body == null) {\n            throw new IOException(\"Empty response body\");\n        }\n\n        String responseStr = body.string();\n        JsonNode root = objectMapper.readTree(responseStr);\n\n        // Check for API error status\n        JsonNode statusNode = root.get(\"status\");\n        String status = statusNode != null ? statusNode.asText() : \"\";\n        if (\"failure\".equals(status)) {\n            JsonNode errorsNode = root.get(\"errors\");\n            String errorMessage = errorsNode != null ? errorsNode.toString() : \"Unknown error\";\n            throw new IOException(\"Docling Fast Server processing failed: \" + errorMessage);","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java#L174-L210","documentation":"After posting the PDF to /v1/convert/file, parseResponse checks response.isSuccessful(). A non-2xx status means the server rejected the conversion request itself; the response body (if any) is appended so the caller sees the server's error text. This is distinct from a 2xx that later reports status:'failure' (error 48).","triggerScenarios":"POST to baseUrl + '/v1/convert/file' returns a non-2xx HTTP code; body string (or empty string) is concatenated into the message.","commonSituations":"Malformed multipart payload; server-side timeout during conversion (504); payload too large (413); server bug returning 500; wrong endpoint/contract due to version mismatch.","solutions":["Read the body fragment in the message to see the server's reason","Retry on 5xx with backoff for transient server faults","Reduce the page range (request.getPageNumbers()) to shrink the payload","Check server version matches the client's expected /v1/convert/file contract","Fall back to Java-only via --hybrid-fallback if the server is unreliable"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    HybridResponse r = client.convert(request);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Docling Fast Server request failed with status\")) {\n        String body = e.getMessage(); // contains the server error text\n        log.error(\"convert rejected by server: {}\", body);\n    }\n    throw e;\n}","preventionTips":["Log the full message — it carries the server's error body","Retry 5xx with exponential backoff; do not retry 4xx","Cap the page range to avoid payload-too-large (413) errors"],"tags":["network","hybrid","docling-fast","http-status","convert"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}