opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Unsupported hybrid backend '%s'. Supported values: %s

Error message

Unsupported hybrid backend '%s'. Supported values: %s

What it means

Thrown when --hybrid receives a non-empty value not in the hybrid backend domain. The value is trimmed and lowercased, then checked via Config.isValidHybrid against {off, docling, docling-fast, hancom, hancom-ai} (azure/google are reserved but not registered until implemented). Any other string is rejected with the bad value and the live supported list.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/cli/CLIOptions.java:660

                if (!format.isEmpty()) {
                    values.add(format);
                }
            }
        }
        return values;
    }

    private static void applyHybridOptions(Config config, CommandLine commandLine) {
        if (commandLine.hasOption(HYBRID_LONG_OPTION)) {
            String hybridValue = commandLine.getOptionValue(HYBRID_LONG_OPTION);
            if (hybridValue == null || hybridValue.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        String.format("Option --hybrid requires a value. Supported values: %s",
                                Config.getHybridOptions(", ")));
            }
            String hybrid = hybridValue.trim().toLowerCase(Locale.ROOT);
            if (!Config.isValidHybrid(hybrid)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported hybrid backend '%s'. Supported values: %s",
                                hybrid, Config.getHybridOptions(", ")));
            }
            config.setHybrid(hybrid);
        }
        if (commandLine.hasOption(HYBRID_MODE_LONG_OPTION)) {
            String modeValue = commandLine.getOptionValue(HYBRID_MODE_LONG_OPTION);
            if (modeValue == null || modeValue.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        String.format("Option --hybrid-mode requires a value. Supported values: %s",
                                Config.getHybridModeOptions(", ")));
            }
            String mode = modeValue.trim().toLowerCase(Locale.ROOT);
            if (!Config.isValidHybridMode(mode)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported hybrid mode '%s'. Supported values: %s",
                                mode, Config.getHybridModeOptions(", ")));
            }

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Use one of the registered backends: off, docling, docling-fast, hancom, hancom-ai.
  2. Mind the hyphen in hancom-ai.
  3. Confirm the backend you want is implemented in your version (check the error's listed values).

Example fix

// before
opendataloader-pdf doc.pdf --hybrid azure
// after
opendataloader-pdf doc.pdf --hybrid hancom-ai
Defensive patterns

Strategy: type-guard

Validate before calling

String h = userValue.trim().toLowerCase(Locale.ROOT);
if (!Config.isValidHybrid(h)) {
    throw new IllegalArgumentException(
        "Unsupported hybrid backend '" + userValue + "'. Use: " + Config.getHybridOptions(", "));
}

Type guard

boolean isAcceptableHybrid(String v) {
    return v != null && Config.isValidHybrid(v.trim().toLowerCase(Locale.ROOT));
}

Try / catch

try {
    config.setHybrid(h);
} catch (IllegalArgumentException e) {
    config.setHybrid(Config.HYBRID_OFF);
}

Prevention

When it happens

Trigger: Pass `--hybrid azure` or `--hybrid google` (not yet implemented, so not in the valid set), a typo like `hancomai` (missing hyphen), or `--hybrid doclings`.

Common situations: Trying a backend before its integration is shipped (azure/google); dropping the hyphen in hancom-ai; using the deprecated docling-fast alias works but is discouraged.

Related errors

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