apache/seatunnel · error · ParameterException

Sample dry-run mode requires --master/--deploy-mode local.

Error message

Sample dry-run mode requires --master/--deploy-mode local.

What it means

ClientCommandArgs.validateSampleMode() throws this picocli ParameterException when --dry-run sample is used with a master/deploy-mode other than local. Sample dry-run executes the pipeline in-process on a local engine, so a cluster master target is meaningless and rejected up front.

Source

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

    }

    /** Validates options that depend on other command-line arguments. */
    public void validateCommandOptions() {
        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

View on GitHub (pinned to cf67b549a7)

Solutions

1. Drop --master/--deploy-mode or set it to local: --master local
2. If cluster execution is required, remove --dry-run sample and run the job normally

Example fix

// before
--dry-run sample --master cluster
// after
--dry-run sample --master local

if (dryRun === 'sample' && masterType !== 'local') {
  throw new Error('--dry-run sample requires --master local');
}

try {
  seatunnel.run(args);
} catch (ParameterException e) {
  if (e.getMessage().contains('requires --master/--deploy-mode local')) {
    args.add('--master').add('local');
  } else { throw e; }
}

When it happens

Trigger: Running with `--dry-run sample` while --master is set to cluster (or any MasterType != LOCAL), e.g. `--dry-run sample --master cluster`.

Common situations: Copying a cluster-submission command line and adding --dry-run sample; CI scripts that default to --master cluster; forgetting that sample mode implies local execution.

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 does not support --async.
• 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/a04eafde20bb0237. Report an issue: GitHub.