opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Invalid ocrStrategy: %s (expected off, auto, or force)

Error message

Invalid ocrStrategy: %s (expected off, auto, or force)

What it means

HybridConfig.setOcrStrategy() accepts exactly three values: OCR_OFF ('off', stream-based enrichment only), OCR_AUTO ('auto', the default — try stream first, fall back to OCR words), or OCR_FORCE ('force', skip stream enrichment, always use OCR). The strategy controls how text is enriched on pages processed by the hybrid backend. Any other non-null value is rejected. Null is allowed (meaning 'use default auto').

Source

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

    }

    /**
     * Sets the OCR strategy for enrichment fallback.
     *
     * <ul>
     *   <li>{@code "off"}: stream-based enrichment only, no OCR fallback</li>
     *   <li>{@code "auto"} (default): try stream enrichment first, fall back to OCR words when no match</li>
     *   <li>{@code "force"}: skip stream enrichment, always use OCR words</li>
     * </ul>
     *
     * @param ocrStrategy The OCR strategy to use.
     */
    public void setOcrStrategy(String ocrStrategy) {
        if (ocrStrategy != null
                && !OCR_OFF.equals(ocrStrategy)
                && !OCR_AUTO.equals(ocrStrategy)
                && !OCR_FORCE.equals(ocrStrategy)) {
            throw new IllegalArgumentException("Invalid ocrStrategy: "
                + ocrStrategy + " (expected " + OCR_OFF + ", " + OCR_AUTO
                + ", or " + OCR_FORCE + ")");
        }
        this.ocrStrategy = ocrStrategy;
    }

    /**
     * Checks if OCR strategy is auto (stream first, OCR fallback).
     *
     * @return true if strategy is auto, false otherwise.
     */
    public boolean isOcrAuto() {
        return OCR_AUTO.equals(ocrStrategy);
    }

    /**
     * Checks if OCR strategy is force (OCR only).
     *

View on GitHub (pinned to a7789b8e77)

Solutions

1. Use exactly 'off', 'auto', or 'force' (lowercase).
2. Pass null to keep the default ('auto').
3. Trim whitespace from config values.
4. Use the constants: HybridConfig.OCR_OFF, HybridConfig.OCR_AUTO, HybridConfig.OCR_FORCE.

Example fix

// before: synonym rejected
config.setOcrStrategy("automatic");

// after: use the constant or exact string
config.setOcrStrategy(HybridConfig.OCR_AUTO);
// or: config.setOcrStrategy("auto");

String strategy = configSource.get("ocrStrategy");
Set<String> valid = Set.of(
    HybridConfig.OCR_OFF,
    HybridConfig.OCR_AUTO,
    HybridConfig.OCR_FORCE
);
if (strategy != null && !valid.contains(strategy)) {
    throw new IllegalArgumentException(
        "Invalid ocrStrategy '" + strategy + "'. Valid: " + valid);
}
config.setOcrStrategy(strategy); // null = use default (auto)

public static boolean isValidOcrStrategy(String strategy) {
    return strategy == null
        || HybridConfig.OCR_OFF.equals(strategy)
        || HybridConfig.OCR_AUTO.equals(strategy)
        || HybridConfig.OCR_FORCE.equals(strategy);
}

try {
    config.setOcrStrategy(strategy);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid ocrStrategy")) {
        config.setOcrStrategy(HybridConfig.OCR_AUTO); // default
        LOGGER.warning("Invalid ocrStrategy, using default: auto");
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling config.setOcrStrategy('Off'), config.setOcrStrategy('automatic'), config.setOcrStrategy('forced'), or any variant with wrong casing, synonym, or typo. The check is case-sensitive.

Common situations: CLI flag `--ocr-strategy automatic` (synonym instead of 'auto'); config file using 'Auto' (capitalized); trailing whitespace; user assumes 'always' instead of 'force'.

Related errors

• Invalid regionlistStrategy: %s (expected table-first or list
• Invalid imageCache: %s (expected "memory" or "disk")
• Unsupported hybrid backend '%s'. Supported values: %s
• Option --%s: unsupported value '%s'. Supported values: %s, %
• Hybrid backend type cannot be null or empty

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