opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Options --hybrid-hancom-ai-* require --hybrid=hancom-ai (got

Error message

Options --hybrid-hancom-ai-* require --hybrid=hancom-ai (got --hybrid=%s)

What it means

Thrown during CLI parsing when one or more --hybrid-hancom-ai-* options (regionlist-strategy, ocr-strategy, image-cache, save-crops, crop-output-dir) are present but --hybrid is not set to hancom-ai. These options only configure the Hancom AI backend, so the parser rejects them for any other backend to prevent silent misconfiguration. The check is an IllegalArgumentException raised in CLIOptions.applyOptions before any processing starts.

Source

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

        }
        if (commandLine.hasOption(HYBRID_HANCOM_AI_CROP_OUTPUT_DIR_LONG_OPTION)) {
            String value = commandLine.getOptionValue(HYBRID_HANCOM_AI_CROP_OUTPUT_DIR_LONG_OPTION);
            if (value != null && !value.trim().isEmpty()) {
                config.getHybridConfig().setCropOutputDir(value.trim());
            }
        }
        if (commandLine.hasOption(TO_STDOUT_LONG_OPTION)) {
            config.setOutputStdout(true);
        }
        // Keep in sync with all HYBRID_HANCOM_AI_*_LONG_OPTION constants above.
        boolean usesHancomAiOnly =
                commandLine.hasOption(HYBRID_HANCOM_AI_REGIONLIST_STRATEGY_LONG_OPTION) ||
                commandLine.hasOption(HYBRID_HANCOM_AI_OCR_STRATEGY_LONG_OPTION) ||
                commandLine.hasOption(HYBRID_HANCOM_AI_IMAGE_CACHE_LONG_OPTION) ||
                commandLine.hasOption(HYBRID_HANCOM_AI_SAVE_CROPS_LONG_OPTION) ||
                commandLine.hasOption(HYBRID_HANCOM_AI_CROP_OUTPUT_DIR_LONG_OPTION);
        if (usesHancomAiOnly && !Config.HYBRID_HANCOM_AI.equals(config.getHybrid())) {
            throw new IllegalArgumentException(
                    "Options --hybrid-hancom-ai-* require --hybrid=hancom-ai (got --hybrid="
                    + config.getHybrid() + ")");
        }
    }

    /**
     * Exports CLI option definitions as JSON for code generation.
     * This is used to generate Node.js, Python, and documentation from a single
     * source of truth.
     *
     * @param out The output stream to write JSON to
     */
    public static void exportOptionsAsJson(PrintStream out) {
        List<OptionDefinition> exportable = OPTION_DEFINITIONS.stream()
                .filter(d -> d.exported)
                .collect(Collectors.toList());

        // Build JSON manually to avoid external dependencies

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Add --hybrid=hancom-ai to the same command line as the --hybrid-hancom-ai-* flags
  2. Remove the --hybrid-hancom-ai-* options if you actually intend to run the docling/docling-fast backend
  3. If configuring programmatically, call config.setHybrid(Config.HYBRID_HANCOM_AI) before or alongside setting HybridConfig fields

Example fix

// before
opendataloader-pdf --hybrid=docling-fast --hybrid-hancom-ai-ocr-strategy force in.pdf
// after
opendataloader-pdf --hybrid=hancom-ai --hybrid-hancom-ai-ocr-strategy force in.pdf
Defensive patterns

Strategy: validation

Validate before calling

// Validate before invoking CLIOptions.parse / building Config
Set<String> hancomOnly = Set.of(
    "--hybrid-hancom-ai-regionlist-strategy",
    "--hybrid-hancom-ai-ocr-strategy",
    "--hybrid-hancom-ai-image-cache",
    "--hybrid-hancom-ai-save-crops",
    "--hybrid-hancom-ai-crop-output-dir");
boolean usesHancom = Arrays.stream(args).anyMatch(hancomOnly::contains);
boolean isHancom = Arrays.stream(args)
    .filter(a -> a.startsWith("--hybrid=") && !a.startsWith("--hybrid-"))
    .anyMatch(a -> a.equals("--hybrid=hancom-ai"));
if (usesHancom && !isHancom) {
    throw new IllegalArgumentException(
        "--hybrid-hancom-ai-* flags require --hybrid=hancom-ai");
}

Try / catch

// If you cannot pre-validate, catch at parse time
try {
    CLIOptions.parse(args, config);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("require --hybrid=hancom-ai")) {
        System.err.println(e.getMessage());
        System.err.println("Re-run with --hybrid=hancom-ai or remove the hancom-only flags.");
        System.exit(2);
    }
    throw e;
}

Prevention

When it happens

Trigger: Passing any of --hybrid-hancom-ai-regionlist-strategy, --hybrid-hancom-ai-ocr-strategy, --hybrid-hancom-ai-image-cache, --hybrid-hancom-ai-save-crops, or --hybrid-hancom-ai-crop-output-dir while --hybrid is unset, set to docling/docling-fast, or any value other than the literal 'hancom-ai' (compared at CLIOptions.java:767 against Config.HYBRID_HANCOM_AI).

Common situations: Copy-pasting Hancom-specific flags from a config meant for the Hancom backend while pointing --hybrid at docling; migrating backends and forgetting to switch the --hybrid value; stale flags left in a wrapper script or CI matrix; setting config.setHybrid() after the hancom-ai config fields are already populated via the API.

Related errors

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