opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --format requires at least one value. Supported value

Error message

Option --format requires at least one value. Supported values: json, text, html, pdf, markdown, tagged-pdf

What it means

First of two guards on --format: fires when getOptionValues returns null or a zero-length array while the option is present. The --format option accepts repeated/comma-separated output formats, so it uses the array form; an absent value array is a usage error. Supported values are json, text, html, pdf, markdown, tagged-pdf (markdown-with-html and markdown-with-images are accepted but deprecated).

Source

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

                            value));
            }
        }
    }

    private static void applySanitizeOption(Config config, CommandLine commandLine) {
        if (commandLine.hasOption(SANITIZE_LONG_OPTION)) {
            config.getFilterConfig().setFilterSensitiveData(true);
        }
    }

    private static void applyFormatOption(Config config, CommandLine commandLine) {
        if (!commandLine.hasOption(FORMAT_OPTION)) {
            return;
        }

        String[] optionValues = commandLine.getOptionValues(FORMAT_OPTION);
        if (optionValues == null || optionValues.length == 0) {
            throw new IllegalArgumentException(
                    "Option --format requires at least one value. Supported values: json, text, html, pdf, markdown, tagged-pdf");
        }

        Set<String> values = parseOptionValues(optionValues);
        if (values.isEmpty()) {
            throw new IllegalArgumentException(
                    "Option --format requires at least one value. Supported values: json, text, html, pdf, markdown, tagged-pdf");
        }

        config.setGenerateJSON(false);

        for (String value : values) {
            switch (value) {
                case "json":
                    config.setGenerateJSON(true);
                    break;
                case "html":
                    config.setGenerateHtml(true);

View on GitHub (pinned to a7789b8e77)

Solutions

Pass at least one format: `--format json` or `-f json`.
Combine formats comma-separated: `--format json,markdown`.
Omit the flag to keep the default (json).

Example fix

// before
opendataloader-pdf doc.pdf -f
// after
opendataloader-pdf doc.pdf -f json,markdown

Defensive patterns

Strategy: validation

Validate before calling

String[] vals = commandLine.getOptionValues("format");
if (commandLine.hasOption("format") && (vals == null || vals.length == 0)) {
    throw new IllegalArgumentException("--format needs at least one value");
}

Type guard

boolean hasFormatValues(CommandLine cmd) {
    String[] v = cmd.getOptionValues("format");
    return v != null && v.length > 0;
}

Try / catch

try {
    CLIOptions.applyAllTo(config, cmd);
} catch (IllegalArgumentException e) {
    System.err.println(e.getMessage());
    printUsage();
    System.exit(2);
}

Prevention

Always pass at least one format with -f/--format.
Default to json by omitting the flag when unsure.
When extending Options via addAllTo, keep the format option's value arity intact.

When it happens

Trigger: Run `--format` with no token, or a parse that yields the flag but no arguments. Note `--format` short form is `-f`.

Common situations: Bare flag in a generated command; a wrapper that adds `-f` without its values; misconfigured arity in an external Options builder that reuses addAllTo.

Related errors

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