opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --threads requires an integer >= 1, got '%s'

Error message

Option --threads requires an integer >= 1, got '%s'

What it means

applyThreadsOption calls Integer.parseInt on the --threads value; if it is not a base-10 integer, NumberFormatException is wrapped in an IllegalArgumentException with this message. This is the 'unparseable' branch; the value string is quoted in the message. Note parseLong overflow or 1.5 also land here because Integer.parseInt rejects them.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/cli/CLIOptions.java:432

        applyFormatOption(config, commandLine);
        applyTableMethodOption(config, commandLine);
        applyImageOptions(config, commandLine);
        applyPagesOption(config, commandLine);
        applyHybridOptions(config, commandLine);
        applyThreadsOption(config, commandLine);
        config.normalize();
    }

    private static void applyThreadsOption(Config config, CommandLine commandLine) {
        if (!commandLine.hasOption(THREADS_LONG_OPTION)) {
            return;
        }
        String value = commandLine.getOptionValue(THREADS_LONG_OPTION);
        int requested;
        try {
            requested = Integer.parseInt(value.trim());
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(
                    String.format("Option --threads requires an integer >= 1, got '%s'", value));
        }
        if (requested < 1) {
            throw new IllegalArgumentException(
                    String.format("Option --threads requires an integer >= 1, got %d", requested));
        }
        config.setThreads(requested);
        int applied = config.getThreads();
        if (applied < requested) {
            System.err.println(String.format(
                    "Warning: --threads=%d exceeds available CPU cores; capped to %d.",
                    requested, applied));
        }
    }

    private static void applyImageOptions(Config config, CommandLine commandLine) {
        if (commandLine.hasOption(IMAGE_OUTPUT_LONG_OPTION)) {
            String outputValue = commandLine.getOptionValue(IMAGE_OUTPUT_LONG_OPTION);

View on GitHub (pinned to a7789b8e77)

Solutions

1. Pass a plain base-10 integer (e.g. 4).
2. If the value comes from an env/config source, coerce with Integer.parseInt and handle the exception before invoking the CLI.

Example fix

# before: --threads 1.5
# after:  --threads 2

int n;
try {
    n = Integer.parseInt(rawThreads.trim());
} catch (NumberFormatException e) {
    throw new IllegalArgumentException("--threads must be an integer >= 1: " + rawThreads, e);
}
if (n < 1) throw new IllegalArgumentException("--threads must be >= 1: " + n);
config.setThreads(n);

static boolean isParsableThreadCount(String s) {
    try { Integer.parseInt(s.trim()); return true; } catch (NumberFormatException e) { return false; }
}

try { /* build config with --threads */ }
catch (IllegalArgumentException e) { /* reprompt: integer thread count */ }

When it happens

Trigger: CLI --threads abc, --threads 1.5, --threads 0x4.

Common situations: Passing a decimal thread count; non-numeric paste; hex notation; locale decimal separator.

Related errors

• Option --space-ratio requires valid double value.
• Option --threads requires an integer >= 1, got %d
• Invalid page range format: '%s'. Expected format: 1,3,5-7
• threads must be >= 1, got {threads}
• Option --space-ratio requires a finite positive double value

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