apache/seatunnel · error · ParameterException

${name} must not exceed ${DryRunSampleConfig.MAX_LIMIT}.

Error message

${name} must not exceed ${DryRunSampleConfig.MAX_LIMIT}.

What it means

PositiveIntegerValidator throws this ParameterException when --sample-limit exceeds DryRunSampleConfig.MAX_LIMIT. The upper bound protects the local sample engine from fetching/printing an unbounded number of records.

Source

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

    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) {
                throw new ParameterException(name + " must be an integer.", e);
            }
        }
    }

    public static class SeaTunnelMasterTargetConverter implements IStringConverter<MasterType> {
        private static final List<MasterType> MASTER_TYPE_LIST = new ArrayList<>();

        static {
            MASTER_TYPE_LIST.add(MasterType.LOCAL);
            MASTER_TYPE_LIST.add(MasterType.CLUSTER);
        }

        @Override
        public MasterType convert(String value) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Reduce --sample-limit to a value <= DryRunSampleConfig.MAX_LIMIT (check the constant in DryRunSampleConfig for the exact cap)
2. If you need more data than the cap, run the job normally instead of a sample dry-run

Example fix

// before
--sample-limit 1000000
// after
--sample-limit 100

const limit = Number.parseInt(value, 10);
const MAX_LIMIT = /* from DryRunSampleConfig.MAX_LIMIT */;
if (Number.isInteger(limit) && limit > MAX_LIMIT) {
  throw new Error(`--sample-limit must not exceed ${MAX_LIMIT}`);
}

When it happens

Trigger: Running e.g. `--sample-limit 100000` where 100000 > DryRunSampleConfig.MAX_LIMIT.

Common situations: Assuming sample limit is unbounded; copying batch-size values (e.g. 10000) into --sample-limit without checking the cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ${name} must be greater than zero.
• SeaTunnel job on spark engine deploy mode only support these
• --restore and --restore-with-checkpoint are mutually exclusi
• --savepoint and --restore-with-checkpoint are mutually exclu
• --restore-with-checkpoint requires a numeric jobId, got: ${v

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