opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --image-output requires a value. Supported values: %s

Error message

Option --image-output requires a value. Supported values: %s

What it means

applyImageOptions detects that --image-output was supplied but its value is null or whitespace-only (after trim), and throws. This fires before any validity check on the mode itself, so an empty value never reaches the unsupported-mode branch (error [19]).

Source

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

        }
        if (requested < 1) {
            throw new IllegalArgumentException(
                    String.format("Option --threads requires an integer >= 1, got %d", requested));
        }
        config.setThreads(requested);
        int applied = config.getThreads();
        if (applied < requested) {
            System.err.println(String.format(
                    "Warning: --threads=%d exceeds available CPU cores; capped to %d.",
                    requested, applied));
        }
    }

    private static void applyImageOptions(Config config, CommandLine commandLine) {
        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);

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Supply a non-empty value: off, embedded, or external.
  2. Check shell quoting and that the env var backing the value is set before invoking the CLI.

Example fix

# before: --image-output ""   # or --image-output with no arg
# after:  --image-output embedded
Defensive patterns

Strategy: validation

Validate before calling

String v = rawImageOutput;
if (v == null || v.trim().isEmpty()) {
    throw new IllegalArgumentException(
        "--image-output requires a value. Valid: " + Config.getImageOutputOptions(", "));
}

Type guard

static boolean hasImageOutputValue(String s) { return s != null && !s.trim().isEmpty(); }

Try / catch

try { /* build config with --image-output */ }
catch (IllegalArgumentException e) { /* prompt for off|embedded|external */ }

Prevention

When it happens

Trigger: CLI --image-output with no argument, --image-output "" or --image-output " ".

Common situations: Option flag passed but the value was consumed by a quoting/shell mistake; value sourced from an unset env var that expands to empty; argument parser misconfiguration.

Related errors

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