opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Unsupported hybrid backend '%s'. Supported values: %s

Error message

Unsupported hybrid backend '%s'. Supported values: %s

What it means

Config.setHybrid rejects any value not registered in hybridOptions. The actually registered backends are: off, docling, docling-fast (deprecated alias), hancom, hancom-ai. Although the HYBRID_AZURE and HYBRID_GOOGLE string constants exist and the docstring mentions azure/google, they are NOT added to the option set (Config.java:131 comment 'azure, google added when implemented'), so passing them still throws. The check is case-insensitive and does not trim whitespace. null is accepted and defaults to off.

Source

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

    /**
     * Gets the hybrid backend name.
     *
     * @return The hybrid backend (off, docling, hancom, azure, google).
     */
    public String getHybrid() {
        return hybrid;
    }

    /**
     * Sets the hybrid backend.
     *
     * @param hybrid The hybrid backend (off, docling, hancom, azure, google).
     * @throws IllegalArgumentException if the backend is not supported.
     */
    public void setHybrid(String hybrid) {
        if (hybrid != null && !isValidHybrid(hybrid)) {
            throw new IllegalArgumentException(
                String.format("Unsupported hybrid backend '%s'. Supported values: %s",
                    hybrid, getHybridOptions(", ")));
        }
        this.hybrid = hybrid != null ? hybrid.toLowerCase(Locale.ROOT) : HYBRID_OFF;
    }

    /**
     * Gets the list of supported hybrid backend options.
     *
     * @param delimiter The delimiter to use between options.
     * @return The string with hybrid backends separated by the delimiter.
     */
    public static String getHybridOptions(CharSequence delimiter) {
        return String.join(delimiter, hybridOptions);
    }

    /**
     * Checks if the given hybrid backend is valid.

View on GitHub (pinned to a7789b8e77)

Solutions

1. Use a registered backend: off, docling, hancom, or hancom-ai (docling-fast is a deprecated alias that still works).
2. Do not pass azure or google until they are registered in your version.
3. Trim and lowercase externally sourced values; pre-validate with Config.isValidHybrid(value).

Example fix

// before: config.setHybrid("azure");   // throws: not registered yet
// after:  config.setHybrid("hancom");

String backend = externalValue == null ? null : externalValue.trim().toLowerCase(Locale.ROOT);
if (backend != null && !Config.isValidHybrid(backend)) {
    throw new IllegalArgumentException(
        "Bad --hybrid '" + backend + "'. Valid: " + Config.getHybridOptions(", "));
}
config.setHybrid(backend);

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

try {
    config.setHybrid(raw);
} catch (IllegalArgumentException e) {
    config.setHybrid(null); // default off
}

When it happens

Trigger: config.setHybrid("azure") or config.setHybrid("google") (not yet wired up); config.setHybrid("doclng") (typo); an untrimmed value from env.

Common situations: Reading the docstring/Javadoc that lists azure/google and trying them before they are implemented; using the deprecated docling-fast alias; typo; whitespace from config templates.

Related errors

• Hybrid backend type cannot be null or empty
• Unknown hybrid backend: %s. Supported backends: %s
• Timeout must be non-negative: %s
• Max concurrent requests must be positive: %s
• Invalid regionlistStrategy: %s (expected table-first or list

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