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

Config.setImageOutput rejects any value not in {off, embedded, external}. The check is case-insensitive (lowercased) but does not trim whitespace. null is accepted and defaults to external. IllegalArgumentException is thrown before assignment. Note: when reached via the CLI, the CLI layer (error [19]) pre-validates and throws the same message first, so this Config-level path effectively only fires for programmatic API callers.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/Config.java:585

    /**
     * Gets the image output mode.
     *
     * @return The image output mode (off, embedded, or external).
     */
    public String getImageOutput() {
        return imageOutput;
    }

    /**
     * Sets the image output mode.
     *
     * @param imageOutput The image output mode (off, embedded, or external).
     * @throws IllegalArgumentException if the mode is not supported.
     */
    public void setImageOutput(String imageOutput) {
        if (imageOutput != null && !isValidImageOutput(imageOutput)) {
            throw new IllegalArgumentException(
                String.format("Unsupported image output mode '%s'. Supported values: %s",
                    imageOutput, getImageOutputOptions(", ")));
        }
        this.imageOutput = imageOutput != null ? imageOutput.toLowerCase(Locale.ROOT) : IMAGE_OUTPUT_EXTERNAL;
    }

    /**
     * Gets the list of supported image output options.
     *
     * @param delimiter The delimiter to use between options.
     * @return The string with image output modes separated by the delimiter.
     */
    public static String getImageOutputOptions(CharSequence delimiter) {
        return String.join(delimiter, imageOutputOptions);
    }

    /**
     * Checks if the given image output mode is valid.

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Use one of the supported values: off, embedded, or external.
  2. Trim and lowercase values from external sources before passing.
  3. Pre-validate with Config.isValidImageOutput(value).

Example fix

// before: config.setImageOutput("base64");
// after:  config.setImageOutput("embedded");
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    config.setImageOutput(raw);
} catch (IllegalArgumentException e) {
    config.setImageOutput(null); // default external
}

Prevention

When it happens

Trigger: Direct API call config.setImageOutput("base64") or config.setImageOutput(" file"); any unknown mode or untrimmed value.

Common situations: Using a value name from another tool (e.g. "base64" or "inline" instead of "embedded"); typo; whitespace from templated config.

Related errors

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