apache/seatunnel · error · ParameterException

Sample dry-run mode does not support --async.

Error message

Sample dry-run mode does not support --async.

What it means

validateSampleMode() throws this ParameterException when --dry-run sample is combined with the --async flag. Sample mode runs synchronously to print sampled records; async submission is incompatible with that flow and is rejected during CLI validation.

Source

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

        validateSampleOptions();
        if (dryRun == DryRun.SAMPLE) {
            validateSampleMode();
        }
    }

    /**
     * Validates that sample mode runs locally without asynchronous submission, restore, savepoint,
     * validation, job control, encryption, or decryption options.
     *
     * @throws ParameterException when sample mode is combined with an unsupported option
     */
    public void validateSampleMode() {
        if (masterType != MasterType.LOCAL) {
            throw new ParameterException(
                    "Sample dry-run mode requires --master/--deploy-mode local.");
        }
        if (async) {
            throw new ParameterException("Sample dry-run mode does not support --async.");
        }
        if (restoreJobId != null
                || restoreWithCheckpointJobId != null
                || savePointJobId != null
                || checkConfig
                || listJob
                || getRunningJobMetrics
                || jobId != null
                || cancelJobId != null
                || forceCancelJobId != null
                || metricsJobId != null
                || checkpointOverviewJobId != null
                || checkpointHistoryJobId != null
                || encrypt
                || decrypt) {
            throw new ParameterException(
                    "Sample dry-run mode cannot be combined with validation, job control, restore, savepoint, encryption, or decryption options.");
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Remove the --async flag when using --dry-run sample
2. Use sample mode synchronously and inspect the printed sample output

Example fix

// before
--dry-run sample --async
// after
--dry-run sample

if (dryRun === 'sample' && async) {
  throw new Error('--async is not supported with --dry-run sample');
}

try {
  seatunnel.run(args);
} catch (ParameterException e) {
  if (e.getMessage().contains('does not support --async')) {
    args.remove('--async');
    seatunnel.run(args);
  } else { throw e; }
}

When it happens

Trigger: Running `seatunnel.sh --dry-run sample ... --async`.

Common situations: Scripts built for normal (async) cluster submissions being reused for dry-runs; habitually adding --async to speed up job submission.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Sample dry-run mode requires --master/--deploy-mode local.
• Dry-run mode must not be empty.
• Unsupported dry-run mode '${value}'. Currently only [static,
• 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/e5d4bff56648fcff. Report an issue: GitHub.