What causes "Invalid imageCache: %s (expected "memory" or "disk")" in opendataloader-project/opendataloader-pdf?

Use exactly 'memory' or 'disk' (lowercase).

opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Invalid imageCache: %s (expected "memory" or "disk")

Error message

Invalid imageCache: %s (expected "memory" or "disk")

What it means

HybridConfig.setImageCache() accepts exactly two values: 'memory' (default, stores page images in a HashMap in heap) or 'disk' (writes page images to temporary PNG files). The choice trades memory pressure (~25MB per page image in memory) against disk I/O. Any other non-null value is rejected. Null is allowed (meaning 'use default memory').

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HybridConfig.java:288

    /**
     * Gets the page image cache strategy.
     *
     * @return "memory" or "disk".
     */
    public String getImageCache() {
        return imageCache;
    }

    /**
     * Sets the page image cache strategy.
     *
     * @param imageCache "memory" (in-heap HashMap) or "disk" (temp PNG files).
     */
    public void setImageCache(String imageCache) {
        if (imageCache != null
                && !"memory".equals(imageCache) && !"disk".equals(imageCache)) {
            throw new IllegalArgumentException("Invalid imageCache: "
                + imageCache + " (expected \"memory\" or \"disk\")");
        }
        this.imageCache = imageCache;
    }

    /**
     * Checks if cropped figure images should be saved to disk.
     *
     * @return true if save-crops is enabled.
     */
    public boolean isSaveCrops() {
        return saveCrops;
    }

    /**
     * Sets whether to save cropped figure images to disk.
     *
     * @param saveCrops true to save crops.

View on GitHub (pinned to a7789b8e77)

Solutions

Use exactly 'memory' or 'disk' (lowercase).
Pass null to keep the default ('memory').
Trim whitespace from config file values before setting.
Choose 'disk' if processing large documents with many pages to avoid OutOfMemoryError.

Example fix

// before: capitalized variant rejected
config.setImageCache("Memory");

// after: use lowercase exact string
config.setImageCache("memory");
// or for large documents: config.setImageCache("disk");

Defensive patterns

Strategy: validation

Validate before calling

String cache = configSource.get("imageCache");
Set<String> valid = Set.of("memory", "disk");
if (cache != null && !valid.contains(cache)) {
    throw new IllegalArgumentException(
        "Invalid imageCache '" + cache + "'. Valid: " + valid);
}
config.setImageCache(cache); // null = use default (memory)

Type guard

public static boolean isValidImageCache(String imageCache) {
    return imageCache == null || "memory".equals(imageCache) || "disk".equals(imageCache);
}

Try / catch

try {
    config.setImageCache(cache);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid imageCache")) {
        config.setImageCache("memory"); // default
        LOGGER.warning("Invalid imageCache, using default: memory");
    } else {
        throw e;
    }
}

Prevention

Trim whitespace from config file values before setting.
Use lowercase exact strings: 'memory' or 'disk'.
Choose 'disk' for large multi-page documents to reduce heap pressure (~25MB per page in memory).
Pass null to keep the default — do not pass empty string.

When it happens

Trigger: Calling config.setImageCache('Memory'), config.setImageCache('DISK'), config.setImageCache('mem'), or any variant with wrong casing, abbreviation, or typo. The check is case-sensitive.

Common situations: CLI flag `--image-cache MEM` (abbreviation); config file using 'Memory' (capitalized); trailing whitespace; a value from an older API version that accepted different strings.

Related errors

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