opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Unsupported hybrid backend: {}

Error message

Unsupported hybrid backend: {}

What it means

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.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java:860

        // hancom uses HancomSchemaTransformer
        if (Config.HYBRID_HANCOM.equals(hybrid)) {
            return new HancomSchemaTransformer();
        }

        // hancom-ai uses HancomAISchemaTransformer. Thread the regionlist strategy
        // from HybridConfig so --regionlist-strategy is honoured instead of silently
        // falling back to the transformer's default.
        if (Config.HYBRID_HANCOM_AI.equals(hybrid)) {
            HancomAISchemaTransformer transformer = new HancomAISchemaTransformer();
            String regionlistStrategy = config.getHybridConfig() != null
                ? config.getHybridConfig().getRegionlistStrategy() : null;
            if (regionlistStrategy != null) {
                transformer.setRegionlistStrategy(regionlistStrategy);
            }
            return transformer;
        }

        throw new IllegalArgumentException("Unsupported hybrid backend: " + hybrid);
    }

    /**
     * Gets page heights for coordinate transformation.
     */
    private static Map<Integer, Double> getPageHeights(Set<Integer> pageNumbers) {
        Map<Integer, Double> pageHeights = new HashMap<>();

        for (int pageNumber : pageNumbers) {
            BoundingBox pageBbox = DocumentProcessor.getPageBoundingBox(pageNumber);
            if (pageBbox != null) {
                pageHeights.put(pageNumber + 1, pageBbox.getHeight()); // 1-indexed for transformer
            }
        }

        return pageHeights;
    }

View on GitHub (pinned to a7789b8e77)

Solutions

  1. 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.
  2. If you intended a different backend, confirm it is implemented in this version — check options.json / --help for the accepted hybrid values.
  3. After changing CLI options in Java, run npm run sync (per CLAUDE.md) so options.json and bindings reflect the current accepted values.
  4. Null-check config.getHybridBackend() before calling if the value can be unset.

Example fix

// before: unsupported identifier
config.setHybridBackend("docling-fast"); // -> IllegalArgumentException
// after: use the supported constant
config.setHybridBackend(Config.HYBRID_HANCOM_AI);
Defensive patterns

Strategy: validation

Validate before calling

// Validate against the supported constant before processing:
String backend = config.getHybridConfig() != null ? config.getHybridConfig().getHybridBackend() : null;
if (backend != null && !Config.HYBRID_HANCOM_AI.equals(backend)) {
    throw new IllegalArgumentException("Unsupported hybrid backend: " + backend);
}

Type guard

static boolean isUnsupportedBackend(IllegalArgumentException e) {
    return e.getMessage() != null && e.getMessage().startsWith("Unsupported hybrid backend: ");
}

Try / catch

try {
    HybridDocumentProcessor.process(inputPdfName, config);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unsupported hybrid backend: ")) {
        config.getHybridConfig().setHybridBackend(Config.HYBRID_HANCOM_AI);
        HybridDocumentProcessor.process(inputPdfName, config);
    } else throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/445341fd0123a9a2. Report an issue: GitHub.