opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

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

Error message

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

What it means

Thrown while applying --hybrid-mode when the flag is present but its value is missing, null, or blank. The handler validates null/empty, then lowercases and checks Config.isValidHybridMode against {auto, full}. The mode controls triage: auto does dynamic per-page triage, full sends all pages to the backend. Note: full mode is required to receive enrichments (--enrich-formula, --enrich-picture-description) which run only on the backend.

Source

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

        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(", ")));
            }
            config.getHybridConfig().setMode(mode);
        }
        if (commandLine.hasOption(HYBRID_OCR_LONG_OPTION)) {
            // Deprecated: OCR settings are now configured on the hybrid server
            System.err.println("Warning: --hybrid-ocr is deprecated. "
                    + "Configure OCR settings on the hybrid server instead (--ocr-lang, --force-ocr).");
        }
        if (commandLine.hasOption(HYBRID_URL_LONG_OPTION)) {
            String url = commandLine.getOptionValue(HYBRID_URL_LONG_OPTION);

View on GitHub (pinned to a7789b8e77)

Solutions

1. Provide `auto` or `full`.
2. If using --enrich-formula / --enrich-picture-description, use `--hybrid-mode full`.
3. Omit the flag for the default (auto).

Example fix

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

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

boolean isAcceptableHybridMode(String v) {
    return v != null && !v.trim().isEmpty()
        && Config.isValidHybridMode(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-mode` with no token, `--hybrid-mode ""`, or adjacent to another flag that swallows the value.

Common situations: Forgetting the value when enabling enrichments (which require `--hybrid-mode full`); truncated script flag.

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
• Option --hybrid requires a value. Supported values: %s

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