{"record":{"id":"445341fd0123a9a2","repo":"opendataloader-project/opendataloader-pdf","slug":"unsupported-hybrid-backend","errorCode":null,"errorMessage":"Unsupported hybrid backend: {}","messagePattern":"Unsupported hybrid backend: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java","lineNumber":860,"sourceCode":"        // hancom uses HancomSchemaTransformer\n        if (Config.HYBRID_HANCOM.equals(hybrid)) {\n            return new HancomSchemaTransformer();\n        }\n\n        // hancom-ai uses HancomAISchemaTransformer. Thread the regionlist strategy\n        // from HybridConfig so --regionlist-strategy is honoured instead of silently\n        // falling back to the transformer's default.\n        if (Config.HYBRID_HANCOM_AI.equals(hybrid)) {\n            HancomAISchemaTransformer transformer = new HancomAISchemaTransformer();\n            String regionlistStrategy = config.getHybridConfig() != null\n                ? config.getHybridConfig().getRegionlistStrategy() : null;\n            if (regionlistStrategy != null) {\n                transformer.setRegionlistStrategy(regionlistStrategy);\n            }\n            return transformer;\n        }\n\n        throw new IllegalArgumentException(\"Unsupported hybrid backend: \" + hybrid);\n    }\n\n    /**\n     * Gets page heights for coordinate transformation.\n     */\n    private static Map<Integer, Double> getPageHeights(Set<Integer> pageNumbers) {\n        Map<Integer, Double> pageHeights = new HashMap<>();\n\n        for (int pageNumber : pageNumbers) {\n            BoundingBox pageBbox = DocumentProcessor.getPageBoundingBox(pageNumber);\n            if (pageBbox != null) {\n                pageHeights.put(pageNumber + 1, pageBbox.getHeight()); // 1-indexed for transformer\n            }\n        }\n\n        return pageHeights;\n    }\n","sourceCodeStart":842,"sourceCodeEnd":878,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java#L842-L878","documentation":"IllegalArgumentException thrown by the schema-transformer factory when config's hybrid backend identifier is not the one supported constant (Config.HYBRID_HANCOM_AI). It is the only backend currently wired, so any other string (typo, a future backend not yet implemented, or null passed programmatically) reaches the unconditional throw at the end of the method.","triggerScenarios":"Calling the internal transformer factory with a hybrid value that is not equal to Config.HYBRID_HANCOM_AI — e.g. config.setHybridBackend(\"docling\"), a typo, or an old config serialized with a backend name that was renamed/removed.","commonSituations":"A config file or environment variable sets an unsupported backend string. A version upgrade renamed the backend constant and a stale config still references the old name. Programmatic callers passing an arbitrary string instead of the documented constant.","solutions":["Set the hybrid backend to the supported value: use Config.HYBRID_HANCOM_AI (or the matching CLI option) and verify against the current options.json.","If you intended a different backend, confirm it is implemented in this version — check options.json / --help for the accepted hybrid values.","After changing CLI options in Java, run npm run sync (per CLAUDE.md) so options.json and bindings reflect the current accepted values.","Null-check config.getHybridBackend() before calling if the value can be unset."],"exampleFix":"// before: unsupported identifier\nconfig.setHybridBackend(\"docling-fast\"); // -> IllegalArgumentException\n// after: use the supported constant\nconfig.setHybridBackend(Config.HYBRID_HANCOM_AI);","handlingStrategy":"validation","validationCode":"// Validate against the supported constant before processing:\nString backend = config.getHybridConfig() != null ? config.getHybridConfig().getHybridBackend() : null;\nif (backend != null && !Config.HYBRID_HANCOM_AI.equals(backend)) {\n    throw new IllegalArgumentException(\"Unsupported hybrid backend: \" + backend);\n}\n","typeGuard":"static boolean isUnsupportedBackend(IllegalArgumentException e) {\n    return e.getMessage() != null && e.getMessage().startsWith(\"Unsupported hybrid backend: \");\n}","tryCatchPattern":"try {\n    HybridDocumentProcessor.process(inputPdfName, config);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unsupported hybrid backend: \")) {\n        config.getHybridConfig().setHybridBackend(Config.HYBRID_HANCOM_AI);\n        HybridDocumentProcessor.process(inputPdfName, config);\n    } else throw e;\n}","preventionTips":["Always set the backend via Config.HYBRID_HANCOM_AI, not a hardcoded string.","After changing CLI options, run npm run sync so options.json lists the current accepted values.","Null-check getHybridBackend() before calling if the config may be unset."],"tags":["hybrid","config","illegalargument","backend","validation"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}