opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --hybrid requires a value. Supported values: %s

Error message

Option --hybrid requires a value. Supported values: %s

What it means

Thrown while applying --hybrid when the flag is present but its value is missing, null, or blank. The handler checks getOptionValue for null/empty before lowercasing and validating via Config.isValidHybrid. Supported backends are off, docling, docling-fast (deprecated alias), hancom, hancom-ai; the message is generated dynamically from Config.getHybridOptions.

Source

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

            if (rawValue == null) {
                continue;
            }
            String[] splitValues = rawValue.split(",");
            for (String candidate : splitValues) {
                String format = candidate.trim().toLowerCase(Locale.ROOT);
                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(", ")));
            }

View on GitHub (pinned to a7789b8e77)

Solutions

1. Supply a backend: `--hybrid hancom-ai` or `--hybrid docling`.
2. Use `--hybrid=off` to explicitly disable.
3. Omit the flag (default is off).

Example fix

// before
opendataloader-pdf doc.pdf --hybrid
// after
opendataloader-pdf doc.pdf --hybrid hancom-ai

String v = commandLine.getOptionValue("hybrid");
if (v != null && !v.trim().isEmpty() && !Config.isValidHybrid(v.trim().toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("Bad --hybrid: " + v);
}

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

try {
    CLIOptions.applyAllTo(config, cmd);
} catch (IllegalArgumentException e) {
    System.err.println("Bad CLI args: " + e.getMessage());
    System.exit(2);
}

When it happens

Trigger: Run `--hybrid` with no token, `--hybrid ""`, or `--hybrid --hybrid-url http://...` where the URL token is consumed or absent.

Common situations: Truncated flag in a script; equals form `--hybrid=` empty; a launcher that injects the backend name from an unset variable.

Related errors

• Option --image-format requires a value. Supported values: pn
• Option --table-method requires a value. Supported values: %s
• Option --content-safety-off requires at least one value. Sup
• Option --format requires at least one value. Supported value
• Unsupported hybrid backend '%s'. Supported values: %s

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