opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --image-format requires a value. Supported values: pn

Error message

Option --image-format requires a value. Supported values: png, jpeg

What it means

Thrown while applying the --image-format CLI option when the flag is present but its argument is missing, null, or blank. CLIOptions guards every value-bearing flag by checking getOptionValue() for null/empty before normalizing, because Apache Commons CLI can surface a present-but-valueless option (e.g. when the next token looks like another flag). The accepted values are exactly png and jpeg (case-insensitive; lowercased via Locale.ROOT before use).

Source

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

        if (commandLine.hasOption(IMAGE_OUTPUT_LONG_OPTION)) {
            String outputValue = commandLine.getOptionValue(IMAGE_OUTPUT_LONG_OPTION);
            if (outputValue == null || outputValue.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        String.format("Option --image-output requires a value. Supported values: %s",
                                Config.getImageOutputOptions(", ")));
            }
            String output = outputValue.trim().toLowerCase(Locale.ROOT);
            if (!Config.isValidImageOutput(output)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported image output mode '%s'. Supported values: %s",
                                output, Config.getImageOutputOptions(", ")));
            }
            config.setImageOutput(output);
        }
        if (commandLine.hasOption(IMAGE_FORMAT_LONG_OPTION)) {
            String formatValue = commandLine.getOptionValue(IMAGE_FORMAT_LONG_OPTION);
            if (formatValue == null || formatValue.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        "Option --image-format requires a value. Supported values: png, jpeg");
            }
            String format = formatValue.trim().toLowerCase(Locale.ROOT);
            if (!Config.isValidImageFormat(format)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported image format '%s'. Supported values: png, jpeg", format));
            }
            config.setImageFormat(format);
        }
        if (commandLine.hasOption(IMAGE_DIR_LONG_OPTION)) {
            config.setImageDir(commandLine.getOptionValue(IMAGE_DIR_LONG_OPTION));
        }
        if (commandLine.hasOption(IMAGE_RESOLUTION_LONG_OPTION)) {
            try {
                double imageResolution = Double.parseDouble(commandLine.getOptionValue(IMAGE_RESOLUTION_LONG_OPTION));
                if (!Double.isFinite(imageResolution) || imageResolution <= 0) {
                    throw new IllegalArgumentException(
                        "Option --image-resolution requires a finite positive double value.");

View on GitHub (pinned to a7789b8e77)

Solutions

1. Supply a value: `--image-format png` or `--image-format jpeg`.
2. Use the equals form with an explicit value: `--image-format=png`.
3. Drop the flag entirely to accept the default (png).
4. If scripting, quote the value and ensure no trailing flag is adjacent.

Example fix

// before
opendataloader-pdf doc.pdf --image-output external --image-format
// after
opendataloader-pdf doc.pdf --image-output external --image-format png

// Before applying CLI, or before calling Config.setImageFormat:
String v = commandLine.getOptionValue("image-format");
if (v != null && !v.trim().isEmpty() && !Config.isValidImageFormat(v.trim().toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("Bad --image-format: " + v);
}

boolean isAcceptableImageFormat(String v) {
    return v != null && !v.trim().isEmpty()
        && Config.isValidImageFormat(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 the CLI with `--image-format` as the last token, or `--image-format ""`, or `--image-format --image-output embedded` (the parser attaches the following flag-shaped token or nothing). Also reachable programmatically if a caller builds a CommandLine where the option is present but getOptionValue returns null.

Common situations: A shell script concatenates flags and forgets the value; an equals form typo like `--image-format=` (empty after split); copy-pasting a long option string and truncating it; quoting mistakes that drop the argument.

Related errors

• Unsupported image format '%s'. Supported values: png, jpeg
• 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/997a31684b3e93e4. Report an issue: GitHub.