{"record":{"id":"070f3eb174ec1b2c","repo":"opendataloader-project/opendataloader-pdf","slug":"backend-processing-failed-for-d-page-s-with-fall","errorCode":null,"errorMessage":"Backend processing failed for %d page(s) with fallback disabled: pages %s","messagePattern":"Backend processing failed for (.+?) page\\(s\\) with fallback disabled: pages (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java","lineNumber":493,"sourceCode":"     * making backend failures invisible to automation.\n     *\n     * @param backendFailedPages 0-indexed pages that the backend failed to process.\n     * @param hybridConfig       Hybrid configuration; consulted for the fallback flag.\n     * @throws IOException if {@code backendFailedPages} is non-empty and\n     *                     {@code hybridConfig.isFallbackToJava()} returns false. The\n     *                     exception message lists the 1-indexed failed page numbers.\n     */\n    static void failFastIfBackendFailedWithoutFallback(\n            Set<Integer> backendFailedPages,\n            HybridConfig hybridConfig) throws IOException {\n        Objects.requireNonNull(backendFailedPages, \"backendFailedPages\");\n        Objects.requireNonNull(hybridConfig, \"hybridConfig\");\n        if (backendFailedPages.isEmpty() || hybridConfig.isFallbackToJava()) {\n            return;\n        }\n        List<Integer> failedPages1Indexed = backendFailedPages.stream()\n            .map(p -> p + 1).sorted().collect(Collectors.toList());\n        throw new IOException(String.format(\n            \"Backend processing failed for %d page(s) with fallback disabled: pages %s\",\n            backendFailedPages.size(), failedPages1Indexed));\n    }\n\n    /**\n     * Filters all pages using ContentFilterProcessor.\n     */\n    private static Map<Integer, List<IObject>> filterAllPages(\n            String inputPdfName,\n            Config config,\n            Set<Integer> pagesToProcess,\n            int totalPages) throws IOException {\n\n        Map<Integer, List<IObject>> filteredContents = new HashMap<>();\n\n        for (int pageNumber = 0; pageNumber < totalPages; pageNumber++) {\n            if (!shouldProcessPage(pageNumber, pagesToProcess)) {\n                filteredContents.put(pageNumber, new ArrayList<>());","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java#L475-L511","documentation":"IOException thrown by failFastIfBackendFailedWithoutFallback when the backend returned partial_success — it processed some pages but populated backendFailedPages with the ones it could not handle — and hybridConfig.isFallbackToJava() is false. The message lists the count and the 1-indexed failed page numbers. This is distinct from error 84 (whole-backend crash): here the backend responded but failed on specific pages.","triggerScenarios":"processBackendPath returns with a non-empty backendFailedPages set (backend reported partial_success), hybridConfig.isFallbackToJava() is false, so failFastIfBackendFailedWithoutFallback throws rather than silently leaving gaps in the output.","commonSituations":"Backend times out or errors on a few complex/corrupt pages while succeeding on the rest, and the operator runs with --hybrid-fallback off for strict semantics. A backend version that cannot handle a particular page feature (e.g. a huge image) returns partial_success.","solutions":["Enable fallback so failed pages are reprocessed through the Java path: set hybridConfig.setFallbackToJava(true) / --hybrid-fallback.","Inspect the listed pages (1-indexed in the message): open those pages in the source PDF and check for corruption, excessive size, or unsupported features, then re-run after fixing the source.","If strict no-fallback is policy, fix or upgrade the backend so it handles those pages, then retry.","Increase backend timeout (hybrid_timeout) if the failures look like per-page timeouts on heavy pages."],"exampleFix":"# before: backend partial success, no fallback -> fail\n$ odl-pdf doc.pdf --hybrid docling-fast --hybrid-url http://b:8080 --hybrid-fallback off\n-> Backend processing failed for 2 page(s) with fallback disabled: pages [7, 12]\n# after: let failed pages fall back to Java\n$ odl-pdf doc.pdf --hybrid docling-fast --hybrid-url http://b:8080 --hybrid-fallback on","handlingStrategy":"fallback","validationCode":"// Inspect the message's page list and decide before failing:\n// If per-page fallback is acceptable, set isFallbackToJava(true) before processing.\nboolean strict = !config.getHybridConfig().isFallbackToJava();\nif (strict) log.warn(\"Backend partial failures will hard-stop the run (fallback disabled)\");\n","typeGuard":"static boolean isPartialBackendFailureNoFallback(IOException e) {\n    return e.getMessage() != null\n        && e.getMessage().startsWith(\"Backend processing failed for \")\n        && e.getMessage().contains(\"with fallback disabled\");\n}","tryCatchPattern":"try {\n    HybridDocumentProcessor.process(inputPdfName, config);\n} catch (IOException e) {\n    var m = e.getMessage();\n    if (m != null && m.startsWith(\"Backend processing failed for \") && m.contains(\"with fallback disabled\")) {\n        // e.g. \"... 2 page(s) ... pages [7, 12]\" — inspect those pages or enable fallback\n        config.getHybridConfig().setFallbackToJava(true);\n        HybridDocumentProcessor.process(inputPdfName, config);\n    } else throw e;\n}","preventionTips":["Enable fallback if you can tolerate Java-quality output on a few pages.","Increase hybrid_timeout if failures look like per-page timeouts on heavy pages.","Parse the 1-indexed page list from the message to pinpoint problematic pages in the source PDF."],"tags":["hybrid","backend","partial-failure","fallback","pages"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}