apache/seatunnel · error · ParameterException

--sample-limit and --sample-print-data require --dry-run sam

Error message

--sample-limit and --sample-print-data require --dry-run sample.

What it means

validateSampleOptions() throws this ParameterException when --sample-limit or --sample-print-data is passed without --dry-run sample. These options only configure sample dry-runs, so specifying them with another dry-run mode (or none) is a usage error.

Source

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

                || 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) {
                    throw new ParameterException(name + " must be greater than zero.");
                }
                if (limit > DryRunSampleConfig.MAX_LIMIT) {
                    throw new ParameterException(
                            name + " must not exceed " + DryRunSampleConfig.MAX_LIMIT + ".");
                }
            } catch (NumberFormatException e) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add --dry-run sample to the command when using --sample-limit/--sample-print-data
2. Remove --sample-limit/--sample-print-data if you don't intend a sample dry-run

Example fix

// before
--sample-limit 5
// after
--dry-run sample --sample-limit 5

if ((sampleLimit != null || samplePrintData) && dryRun !== 'sample') {
  throw new Error('--sample-limit/--sample-print-data require --dry-run sample');
}

When it happens

Trigger: Running `--sample-print-data` alone, `--dry-run static --sample-limit 5`, or any combination where dryRun != SAMPLE but sample options are present.

Common situations: Adding sample flags to a normal run or static dry-run; forgetting to add --dry-run sample when tuning sample output.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

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 dry-run mode cannot be combined with validation, job

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