apache/seatunnel · error · ParameterException

${name} must be greater than zero.

Error message

${name} must be greater than zero.

What it means

PositiveIntegerValidator.validate() throws this ParameterException when the value of --sample-limit parses as an integer but is less than 1. The validator enforces the range [1, DryRunSampleConfig.MAX_LIMIT] before the command proceeds.

Source

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

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

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Set --sample-limit to at least 1
  2. Remove --sample-limit to use the default limit instead of 0

Example fix

// before
--sample-limit 0
// after
--sample-limit 1
Defensive patterns

Strategy: validation

Validate before calling

const limit = Number.parseInt(value, 10);
if (Number.isInteger(limit) && limit < 1) {
  throw new Error('--sample-limit must be >= 1');
}

Try / catch

try {
  seatunnel.run(args);
} catch (ParameterException e) {
  if (e.getMessage().endsWith('must be greater than zero.')) {
    // clamp and retry with a valid limit
  }
}

Prevention

When it happens

Trigger: Running `--dry-run sample --sample-limit 0` or `--sample-limit -3`.

Common situations: Trying to disable sampling by passing 0; programmatically computed limits that default to 0.

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

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