opendataloader-project/opendataloader-pdf · error · IllegalArgumentException

Option --content-safety-off requires at least one value. Sup

Error message

Option --content-safety-off requires at least one value. Supported values: all, hidden-text, off-page, tiny, hidden-ocg

What it means

First of two guards on --content-safety-off: fires when commandLine.getOptionValues returns null or a zero-length array, i.e. the option is present (hasOption true) but Apache Commons CLI attached no tokens at all. This flag accepts repeated/comma-separated values, so the array form is used; an absent value array is treated as a usage error rather than silently disabling nothing.

Source

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

            }
            String method = methodValue.trim().toLowerCase(Locale.ROOT);
            if (!Config.isValidTableMethod(method)) {
                throw new IllegalArgumentException(
                        String.format("Unsupported table method '%s'. Supported values: %s",
                                method, Config.getTableMethodOptions(", ")));
            }
            config.setTableMethod(method);
        }
    }

    private static void applyContentSafetyOption(Config config, CommandLine commandLine) {
        if (!commandLine.hasOption(CONTENT_SAFETY_OFF_LONG_OPTION)) {
            return;
        }

        String[] optionValues = commandLine.getOptionValues(CONTENT_SAFETY_OFF_LONG_OPTION);
        if (optionValues == null || optionValues.length == 0) {
            throw new IllegalArgumentException(
                    "Option --content-safety-off requires at least one value. Supported values: all, hidden-text, off-page, tiny, hidden-ocg");
        }

        Set<String> values = parseOptionValues(optionValues);
        if (values.isEmpty()) {
            throw new IllegalArgumentException(
                    "Option --content-safety-off requires at least one value. Supported values: all, hidden-text, off-page, tiny, hidden-ocg");
        }

        for (String value : values) {
            switch (value) {
                case "hidden-text":
                    config.getFilterConfig().setFilterHiddenText(false);
                    break;
                case "off-page":
                    config.getFilterConfig().setFilterOutOfPage(false);
                    break;
                case "tiny":

View on GitHub (pinned to a7789b8e77)

Solutions

Pass at least one value: `--content-safety-off hidden-text`.
Use multiple values: `--content-safety-off hidden-text,off-page` or repeat the flag.
Use `--content-safety-off all` to disable every filter.

Example fix

// before
opendataloader-pdf doc.pdf --content-safety-off
// after
opendataloader-pdf doc.pdf --content-safety-off all

Defensive patterns

Strategy: validation

Validate before calling

String[] vals = commandLine.getOptionValues("content-safety-off");
if (commandLine.hasOption("content-safety-off") && (vals == null || vals.length == 0)) {
    throw new IllegalArgumentException("--content-safety-off needs at least one value");
}

Type guard

boolean hasContentSafetyValues(CommandLine cmd) {
    String[] v = cmd.getOptionValues("content-safety-off");
    return v != null && v.length > 0;
}

Try / catch

try {
    CLIOptions.applyAllTo(config, cmd);
} catch (IllegalArgumentException e) {
    System.err.println(e.getMessage());
    printUsage();
    System.exit(2);
}

Prevention

Always pair --content-safety-off with at least one filter token.
Use `all` to disable every filter in one token.
Confirm the option's value arity matches your Options registration when using addAllTo.

When it happens

Trigger: Run `--content-safety-off` with no following token when the option is registered as requiring values, or a parse where the option is present but stripped of arguments.

Common situations: Option defined with a value-arity but invoked bare; a wrapper that injects the flag without its arguments; shell quoting that drops the argument list.

Related errors

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