apache/seatunnel · error · IllegalArgumentException

Dry-run mode must not be empty.

Error message

Dry-run mode must not be empty.

What it means

ClientCommandArgs.DryRunConverter converts the --dry-run flag value into a DryRun enum. An empty or null value is rejected with IllegalArgumentException 'Dry-run mode must not be empty.' — the flag requires an explicit mode argument (e.g. static). Unsupported mode names produce a different error listing the allowed modes.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java:229

            throw new IllegalArgumentException(blankMessage);
        }
        try {
            Long.parseLong(trimmed);
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(invalidMessagePrefix + value, e);
        }
        return trimmed;
    }

    public DeployMode getDeployMode() {
        return DeployMode.CLIENT;
    }

    public static class DryRunConverter implements IStringConverter<DryRun> {
        @Override
        public DryRun convert(String value) {
            if (value == null || value.trim().isEmpty()) {
                throw new IllegalArgumentException("Dry-run mode must not be empty.");
            }
            String trimmed = value.trim();
            if (DryRun.STATIC.getName().equalsIgnoreCase(trimmed)
                    || DryRun.STATIC.name().equalsIgnoreCase(trimmed)) {
                return DryRun.STATIC;
            }
            if (DryRun.CONNECT.getName().equalsIgnoreCase(trimmed)
                    || DryRun.CONNECT.name().equalsIgnoreCase(trimmed)) {
                return DryRun.CONNECT;
            }
            if (DryRun.SAMPLE.getName().equalsIgnoreCase(trimmed)
                    || DryRun.SAMPLE.name().equalsIgnoreCase(trimmed)) {
                return DryRun.SAMPLE;
            }
            throw new IllegalArgumentException(
                    "Unsupported dry-run mode '"
                            + value
                            + "'. Currently only [static, connect, sample] are supported; shadow"

View on GitHub (pinned to cf67b549a7)

Solutions

1. Provide a mode explicitly: --dry-run static
2. If the script variable may be empty, default it: MODE=${MODE:-static}
3. Check supported mode names via the converter's allowed values (e.g. 'static')

Example fix

// before
--dry-run
// after
--dry-run static

String mode = System.getenv().getOrDefault("DRY_RUN_MODE", "static");
if (mode.trim().isEmpty()) {
    throw new IllegalArgumentException("--dry-run requires a non-empty mode, e.g. static");
}

try {
    client.submit(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Dry-run mode must not be empty")) {
        log.error("Supply a mode: --dry-run static");
    }
}

When it happens

Trigger: Invoking the client with --dry-run and no value (or an empty string value) so the converter receives null/empty input.

Common situations: Users expecting --dry-run to be a boolean flag with a default mode; shell scripts interpolating an empty variable into the dry-run argument, e.g. --dry-run $MODE with MODE unset.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• SeaTunnel job on spark engine deploy mode only support these
• --restore and --restore-with-checkpoint are mutually exclusi
• --savepoint and --restore-with-checkpoint are mutually exclu
• --restore-with-checkpoint requires a numeric jobId, got: ${v
• Unsupported dry-run mode '${value}'. Currently only [static,

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/1c4903853ca2ec76. Report an issue: GitHub.