opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

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

Error message

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

What it means

applyThreadsOption parsed the --threads value as an integer but it is < 1, so it throws this message (the parsed number is shown unquoted). This is the 'parsed but out of legal range' branch, distinct from the unparseable branch (error [16]). If the value is valid (>= 1) but exceeds availableProcessors, it is silently capped and a warning is printed instead of throwing.

Source

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

        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);
            if (outputValue == null || outputValue.trim().isEmpty()) {
                throw new IllegalArgumentException(
                        String.format("Option --image-output requires a value. Supported values: %s",
                                Config.getImageOutputOptions(", ")));

View on GitHub (pinned to a7789b8e77)

Solutions

1. Pass an integer >= 1.
2. For 'use all cores', omit --threads (default 1) or pass the exact availableProcessors count.

Example fix

# before: --threads 0
# after:  --threads 4   # or omit the option

int n = Integer.parseInt(rawThreads.trim());
if (n < 1) {
    throw new IllegalArgumentException("--threads must be >= 1, got " + n);
}
config.setThreads(n);

static boolean isValidThreadCount(String s) {
    try { return Integer.parseInt(s.trim()) >= 1; } catch (NumberFormatException e) { return false; }
}

try { /* build config with --threads */ }
catch (IllegalArgumentException e) { /* reprompt for a value >= 1 */ }

When it happens

Trigger: CLI --threads 0, --threads -2.

Common situations: Passing 0 expecting 'auto' (not supported); negative value from a subtraction that underflows.

Related errors

• Option --threads requires an integer >= 1, got '%s'
• threads must be >= 1, got {threads}
• Option --space-ratio requires a finite positive double value
• Option --space-ratio requires valid double value.
• Option --image-output requires a value. Supported values: %s

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