opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Unsupported image output mode '%s'. Supported values: %s

Error message

Unsupported image output mode '%s'. Supported values: %s

What it means

applyImageOptions trims and lowercases the --image-output value and checks Config.isValidImageOutput; if it is not in {off, embedded, external} it throws this message. Because config.setImageOutput is only called after this check passes, the Config-layer version of this error ([3]) does not fire when the value comes through the CLI. The CLI pre-check is case-insensitive.

Source

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

        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);
            if (!Config.isValidImageFormat(format)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported image format '%s'. Supported values: png, jpeg", format));
            }
            config.setImageFormat(format);
        }

View on GitHub (pinned to a7789b8e77)

Solutions

1. Use one of the supported modes: off, embedded, or external.
2. Map synonyms before invoking: base64 -> embedded, file/path -> external.
3. Pre-validate with Config.isValidImageOutput(value.trim().toLowerCase(Locale.ROOT)).

Example fix

# before: --image-output base64
# after:  --image-output embedded

String mode = rawImageOutput.trim().toLowerCase(Locale.ROOT);
if (!Config.isValidImageOutput(mode)) {
    throw new IllegalArgumentException(
        "Unsupported --image-output '" + mode + "'. Valid: " + Config.getImageOutputOptions(", "));
}
config.setImageOutput(mode);

static boolean isSupportedImageOutput(String s) {
    return s != null && Config.isValidImageOutput(s.trim().toLowerCase(Locale.ROOT));
}

try { /* build config with --image-output */ }
catch (IllegalArgumentException e) { /* map synonyms or reprompt: off|embedded|external */ }

When it happens

Trigger: CLI --image-output base64, --image-output file, --image-output inline (common synonyms that are NOT accepted).

Common situations: Using a mode name borrowed from another tool (e.g. 'base64' instead of 'embedded', 'file' instead of 'external'); renamed value across versions; typo.

Related errors

• Option --image-output requires a value. Supported values: %s
• Unsupported image output mode '%s'. Supported values: %s
• Option --space-ratio requires a finite positive double value
• Option --space-ratio requires valid double value.
• Option --threads requires an integer >= 1, got '%s'

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