{"record":{"id":"83fd96891f9f5fe4","repo":"opendataloader-project/opendataloader-pdf","slug":"unknown-hybrid-backend-s-supported-backends-s","errorCode":null,"errorMessage":"Unknown hybrid backend: %s. Supported backends: %s","messagePattern":"Unknown hybrid backend: (.+?)\\. Supported backends: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridClientFactory.java","lineNumber":104,"sourceCode":"        return CLIENT_CACHE.computeIfAbsent(lowerHybrid, key -> createClient(key, config));\n    }\n\n    /**\n     * Creates a new hybrid client instance.\n     */\n    private static HybridClient createClient(String hybrid, HybridConfig config) {\n        if (BACKEND_DOCLING_FAST.equals(hybrid)) {\n            return new DoclingFastServerClient(config);\n        } else if (BACKEND_HANCOM.equals(hybrid)) {\n            return new HancomClient(config);\n        } else if (BACKEND_HANCOM_AI.equals(hybrid)) {\n            return new HancomAIClient(config);\n        } else if (BACKEND_AZURE.equals(hybrid)) {\n            throw new UnsupportedOperationException(\"Azure Document Intelligence backend is not yet implemented\");\n        } else if (BACKEND_GOOGLE.equals(hybrid)) {\n            throw new UnsupportedOperationException(\"Google Document AI backend is not yet implemented\");\n        } else {\n            throw new IllegalArgumentException(\"Unknown hybrid backend: \" + hybrid +\n                \". Supported backends: \" + getSupportedBackends());\n        }\n    }\n\n    /**\n     * Creates a hybrid client for the specified backend.\n     *\n     * @param hybrid The backend type (e.g., \"docling\", \"hancom\", \"azure\", \"google\").\n     * @param config The configuration for the hybrid client.\n     * @return A new HybridClient instance for the specified backend.\n     * @throws IllegalArgumentException If the backend type is unknown or not supported.\n     * @deprecated Use {@link #getOrCreate(String, HybridConfig)} instead to reuse clients.\n     */\n    @Deprecated\n    public static HybridClient create(String hybrid, HybridConfig config) {\n        return getOrCreate(hybrid, config);\n    }\n","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridClientFactory.java#L86-L122","documentation":"The backend type string passed to the factory does not match any known constant (docling-fast, hancom, hancom-ai, azure, google). This includes typos, case issues (though getOrCreate lowercases the input first), and entirely unrecognized names. The error message lists all supported backends via getSupportedBackends() for immediate guidance. Unlike azure/google (which throw UnsupportedOperationException), this is an IllegalArgumentException — the input is fundamentally wrong, not just unimplemented.","triggerScenarios":"Calling HybridClientFactory.getOrCreate() with a typo like 'hanocom', 'docling' (instead of 'docling-fast'), 'Hancom' (handled by toLowerCase but worth noting), or any completely unrelated string. Also triggered by passing 'docling' when the correct constant is 'docling-fast'.","commonSituations":"CLI typo: `--hybrid hancom` vs `--hybrid hanocom`; using 'docling' instead of 'docling-fast'; truncation or whitespace in a config file value; copy-paste from outdated documentation that used different backend names.","solutions":["Check the error message — it lists all supported backends. Use one of those exact strings.","For docling: the correct value is 'docling-fast', not 'docling'.","For Hancom: use 'hancom' (standard API) or 'hancom-ai' (HOCR SDK), not 'hancom_ai' or 'HancomAI'.","Trim whitespace from config file values before passing to the factory.","Use the public constants: HybridClientFactory.BACKEND_HANCOM, BACKEND_DOCLING_FAST, etc."],"exampleFix":"// before: typo in backend name\nHybridClient client = HybridClientFactory.getOrCreate(\"hanocom\", config);\n\n// after: use the correct constant\nHybridClient client = HybridClientFactory.getOrCreate(\n    HybridClientFactory.BACKEND_HANCOM, config);","handlingStrategy":"validation","validationCode":"Set<String> validBackends = Set.of(\n    HybridClientFactory.BACKEND_DOCLING_FAST,\n    HybridClientFactory.BACKEND_HANCOM,\n    HybridClientFactory.BACKEND_HANCOM_AI,\n    HybridClientFactory.BACKEND_AZURE, // throws UnsupportedOperationException\n    HybridClientFactory.BACKEND_GOOGLE  // throws UnsupportedOperationException\n);\nString normalized = backend.trim().toLowerCase();\nif (!validBackends.contains(normalized)) {\n    throw new IllegalArgumentException(\n        \"Unknown backend '\" + backend + \"'. Valid: \" + HybridClientFactory.getSupportedBackends());\n}","typeGuard":"public static boolean isKnownBackend(String backend) {\n    if (backend == null) return false;\n    String lower = backend.toLowerCase();\n    return HybridClientFactory.BACKEND_DOCLING_FAST.equals(lower)\n        || HybridClientFactory.BACKEND_HANCOM.equals(lower)\n        || HybridClientFactory.BACKEND_HANCOM_AI.equals(lower)\n        || HybridClientFactory.BACKEND_AZURE.equals(lower)\n        || HybridClientFactory.BACKEND_GOOGLE.equals(lower);\n}","tryCatchPattern":"try {\n    client = HybridClientFactory.getOrCreate(backend, config);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Unknown hybrid backend\")) {\n        // Typo or unsupported — show valid options to the user\n        System.err.println(\"Error: \" + e.getMessage());\n        System.err.println(\"Supported: \" + HybridClientFactory.getSupportedBackends());\n        System.exit(1);\n    }\n    throw e;\n}","preventionTips":["Trim and lowercase backend strings before passing to getOrCreate.","Use the public constants (BACKEND_HANCOM, BACKEND_DOCLING_FAST, etc.) instead of string literals.","Display getSupportedBackends() in CLI help text and error messages.","Remember: 'docling' is wrong — the correct value is 'docling-fast'."],"tags":["configuration","validation","hybrid","factory","programming-error"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}