apache/seatunnel · error · IllegalArgumentException

Unsupported dry-run mode '${value}'. Currently only [static,

Error message

Unsupported dry-run mode '${value}'. Currently only [static, connect, sample] are supported; shadow is not implemented yet.

What it means

This IllegalArgumentException is thrown by ClientCommandArgs' dry-run converter (a picocli IStringConverter) when the --dry-run value supplied on the CLI cannot be mapped to a DryRun enum constant. The converter accepts only static, connect, and sample (case-insensitive); 'shadow' is named explicitly as a known-but-unimplemented mode. SeaTunnel throws it during argument parsing, before any job is submitted.

Source

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

        @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"
                            + " is not implemented yet.");
        }
    }

    /** Returns the configured sample limit, or the default limit when it was not specified. */
    public int getSampleLimit() {
        return sampleLimit == null ? DryRunSampleConfig.DEFAULT_LIMIT : sampleLimit;
    }

    /** Validates options that depend on other command-line arguments. */
    public void validateCommandOptions() {
        validateSampleOptions();
        if (dryRun == DryRun.SAMPLE) {
            validateSampleMode();
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Change --dry-run to one of: static, connect, or sample
2. If you intended shadow mode, it is not implemented; use static mode instead
3. Check spelling/case-insensitive match against the three supported names

Example fix

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

const ALLOWED = ['static','connect','sample'];
if (!ALLOWED.includes(dryRun.toLowerCase())) {
  throw new Error(`--dry-run must be one of ${ALLOWED}; got: ${dryRun}`);
}

const isDryRun = (v) => typeof v === 'string' && ['static','connect','sample'].includes(v.toLowerCase());

When it happens

Trigger: Running `seatunnel.sh --dry-run shadow ...` or any misspelled/unsupported value like `--dry-run Statics` that doesn't equal (ignoring case) static/connect/sample or their enum names.

Common situations: Typo in the dry-run flag value; copying docs or an older example that mentions the planned 'shadow' mode; assuming case must be exact and passing e.g. 'STATIC' (actually accepted) vs 'static-mode' (rejected).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Dry-run mode must not be empty.
• Sample dry-run mode requires --master/--deploy-mode local.
• Sample dry-run mode does not support --async.
• Sample dry-run mode cannot be combined with validation, job
• --sample-limit and --sample-print-data require --dry-run sam

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