apache/seatunnel · error · ParameterException

Sample dry-run mode cannot be combined with validation, job

Error message

Sample dry-run mode cannot be combined with validation, job control, restore, savepoint, encryption, or decryption options.

What it means

validateSampleMode() throws this ParameterException when --dry-run sample appears together with any validation/job-control/restore/savepoint/encrypt/decrypt option (e.g. --check-config, --list-job, --restore-job-id, --savepoint-job-id, --encrypt, --decrypt). Sample mode only executes a local sample run, so these mutually exclusive operations are rejected.

Source

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

        }
        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.");
        }
    }

    private void validateSampleOptions() {
        if (dryRun != DryRun.SAMPLE && (sampleLimit != null || samplePrintData)) {
            throw new ParameterException(
                    "--sample-limit and --sample-print-data require --dry-run sample.");
        }
    }

    /** Validates that a sample limit is between 1 and {@link DryRunSampleConfig#MAX_LIMIT}. */
    public static class PositiveIntegerValidator implements IParameterValidator {
        @Override
        public void validate(String name, String value) throws ParameterException {
            try {
                int limit = Integer.parseInt(value);
                if (limit < 1) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Split the operations into separate commands: one for sample dry-run, one for job control/validation
2. Remove any --restore-*, --savepoint, --check-config, --list-job, --metrics-job-id, --encrypt/--decrypt flags from the sample dry-run command

Example fix

// before
--dry-run sample --check-config --encrypt
// after
seatunnel.sh --dry-run sample -c job.conf
seatunnel.sh --check-config -c job.conf

const INCOMPATIBLE = ['--check-config','--list-job','--restore-job-id','--restore-with-checkpoint-job-id','--savepoint-job-id','--cancel-job-id','--force-cancel-job-id','--metrics-job-id','--checkpoint-overview-job-id','--checkpoint-history-job-id','--encrypt','--decrypt'];
if (dryRun === 'sample' && args.some(a => INCOMPATIBLE.includes(a))) {
  throw new Error('--dry-run sample cannot be combined with validation/job-control/restore/savepoint/encrypt/decrypt options');
}

When it happens

Trigger: Command lines like `--dry-run sample --check-config`, `--dry-run sample --list-job`, `--dry-run sample --restore-job-id 123`, or `--dry-run sample --encrypt`.

Common situations: Combining a dry-run with a config-validation or job-management workflow; over-stuffed wrapper scripts that always pass job-control flags.

Related errors

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