{"record":{"id":"6b3c38a4f5b3ef0d","repo":"opendataloader-project/opendataloader-pdf","slug":"invalid-response-missing-document-field","errorCode":null,"errorMessage":"Invalid response: missing 'document' field","messagePattern":"Invalid response: missing 'document' field","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java","lineNumber":223,"sourceCode":"        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);\n        }\n\n        // Log partial_success status\n        if (\"partial_success\".equals(status)) {\n            JsonNode errorsNode = root.get(\"errors\");\n            LOGGER.log(Level.WARNING, \"Backend returned partial_success: {0}\",\n                errorsNode != null ? errorsNode.toString() : \"no error details\");\n        }\n\n        // Extract document content\n        JsonNode documentNode = root.get(\"document\");\n        if (documentNode == null) {\n            throw new IOException(\"Invalid response: missing 'document' field\");\n        }\n\n        JsonNode jsonContent = documentNode.get(\"json_content\");\n\n        // Extract per-page content from json_content if available\n        Map<Integer, JsonNode> pageContents = extractPageContents(jsonContent);\n\n        // Extract failed pages (1-indexed) from partial_success responses\n        List<Integer> failedPages = extractFailedPages(root);\n\n        // Extract per-step pipeline timings (layout, ocr, table_structure, etc.)\n        JsonNode timingsNode = root.get(\"timings\");\n\n        return new HybridResponse(null, null, jsonContent, pageContents, failedPages, timingsNode);\n    }\n\n    /**\n     * Extracts per-page content from the DoclingDocument JSON structure.","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java#L205-L241","documentation":"The response parsed as JSON and did not report status:'failure', but the required 'document' field is absent. parseResponse needs root.get(\"document\") to extract json_content and per-page content, so its absence means the server returned an unexpected schema. This guards against silently producing an empty HybridResponse from a malformed reply.","triggerScenarios":"objectMapper.readTree(body) succeeds and status != 'failure', but root.get(\"document\") returns null.","commonSituations":"Version skew: client expects the docling-serve-compatible envelope but the server returns a different shape; server returns an error wrapped in a non-standard JSON object with status omitted; proxy injecting an unrelated JSON body.","solutions":["Confirm the docling-fast-server version matches the client's expected response schema","Log the raw response body to inspect the actual envelope","Upgrade or downgrade client/server to a compatible pair","Hit the server directly (bypass proxies) to rule out body rewriting"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Not generally possible client-side without the raw body; if you mirror\n// responses in a test double, assert the schema of your mock server:\nassert responseJson.has(\"document\") : \"server must return a 'document' field\";","typeGuard":null,"tryCatchPattern":"try {\n    return client.convert(request);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"missing 'document' field\")) {\n        log.error(\"schema mismatch with docling-fast-server version — align versions\");\n    }\n    throw e;\n}","preventionTips":["Pin client and server to compatible versions","In test doubles, always include the 'document' field in mock responses","Log raw response bodies in staging to catch schema drift early"],"tags":["hybrid","docling-fast","response-parsing","schema"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}