What causes "Invalid regionlistStrategy: %s (expected table-first or list-only)" in opendataloader-project/opendataloader-pdf?

Use exactly 'table-first' or 'list-only' (lowercase, hyphenated).

opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Invalid regionlistStrategy: %s (expected table-first or list

Error message

Invalid regionlistStrategy: %s (expected table-first or list-only)

What it means

HybridConfig.setRegionlistStrategy() accepts exactly two values: REGIONLIST_TABLE_FIRST ('table-first', the default) or REGIONLIST_LIST_ONLY ('list-only'). The strategy controls how label-7 (regionlist) regions are processed: 'table-first' checks table structure recognition (TSR) overlap first and skips list treatment if TSR exists, while 'list-only' always treats them as lists. Any other non-null value is rejected. Null is allowed (meaning 'use default').

Source

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

    public String getRegionlistStrategy() {
        return regionlistStrategy;
    }

    /**
     * Sets the regionlist strategy for label 7 (Table region) handling.
     *
     * <ul>
     *   <li>{@code "table-first"} (default): check TSR overlap, skip if TSR exists, else treat as list</li>
     *   <li>{@code "list-only"}: always treat as list, skip TSR check entirely</li>
     * </ul>
     *
     * @param regionlistStrategy The regionlist strategy to use.
     */
    public void setRegionlistStrategy(String regionlistStrategy) {
        if (regionlistStrategy != null
                && !REGIONLIST_TABLE_FIRST.equals(regionlistStrategy)
                && !REGIONLIST_LIST_ONLY.equals(regionlistStrategy)) {
            throw new IllegalArgumentException("Invalid regionlistStrategy: "
                + regionlistStrategy + " (expected " + REGIONLIST_TABLE_FIRST
                + " or " + REGIONLIST_LIST_ONLY + ")");
        }
        this.regionlistStrategy = regionlistStrategy;
    }

    /**
     * Checks if regionlist strategy is list-only (always treat label 7 as list).
     *
     * @return true if strategy is list-only, false otherwise.
     */
    public boolean isRegionlistListOnly() {
        return REGIONLIST_LIST_ONLY.equals(regionlistStrategy);
    }

    /**
     * Gets the page image cache strategy.
     *

View on GitHub (pinned to a7789b8e77)

Solutions

Use exactly 'table-first' or 'list-only' (lowercase, hyphenated).
Pass null to keep the default ('table-first').
Check for trailing whitespace: trim the value before setting.
Use the constants: HybridConfig.REGIONLIST_TABLE_FIRST or HybridConfig.REGIONLIST_LIST_ONLY.

Example fix

// before: underscore variant rejected
config.setRegionlistStrategy("table_first");

// after: use the constant or exact string
config.setRegionlistStrategy(HybridConfig.REGIONLIST_TABLE_FIRST);
// or: config.setRegionlistStrategy("table-first");

Defensive patterns

Strategy: validation

Validate before calling

String strategy = configSource.get("regionlistStrategy");
Set<String> valid = Set.of(
    HybridConfig.REGIONLIST_TABLE_FIRST,
    HybridConfig.REGIONLIST_LIST_ONLY
);
if (strategy != null && !valid.contains(strategy)) {
    throw new IllegalArgumentException(
        "Invalid regionlistStrategy '" + strategy + "'. Valid: " + valid);
}
config.setRegionlistStrategy(strategy); // null = use default

Type guard

public static boolean isValidRegionlistStrategy(String strategy) {
    return strategy == null
        || HybridConfig.REGIONLIST_TABLE_FIRST.equals(strategy)
        || HybridConfig.REGIONLIST_LIST_ONLY.equals(strategy);
}

Try / catch

try {
    config.setRegionlistStrategy(strategy);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid regionlistStrategy")) {
        // Use default instead of failing
        config.setRegionlistStrategy(HybridConfig.REGIONLIST_TABLE_FIRST);
        LOGGER.warning("Invalid regionlistStrategy, using default: table-first");
    } else {
        throw e;
    }
}

Prevention

Trim whitespace from config file values before setting.
Use the public constants REGIONLIST_TABLE_FIRST and REGIONLIST_LIST_ONLY.
Remember: values are lowercase with hyphens ('table-first'), not underscores or camelCase.
Pass null to keep the default — do not pass empty string.

When it happens

Trigger: Calling config.setRegionlistStrategy('tableFirst'), config.setRegionlistStrategy('list_only'), or any variant with different casing, underscores, or typos. The check is case-sensitive — 'Table-First' or 'TABLE-FIRST' will fail.

Common situations: CLI flag `--regionlist-strategy table_first` (underscore instead of hyphen); config file using camelCase 'tableFirst'; copy-paste from documentation that used a different convention; trailing whitespace in a properties file value.

Related errors

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