apache/seatunnel · error · ParameterException

must be an integer.

Error message

${name} must be an integer.

What it means

PositiveIntegerValidator throws this ParameterException (wrapping the NumberFormatException) when --sample-limit is not a parseable integer. This is the standard picocli IParameterValidator flow invoked before command execution.

Solutions

1. Pass a plain integer value, e.g. --sample-limit 10
2. Shell-quote properly so the flag doesn't receive an empty string
3. Check the script/CI variable actually contains a number before substituting it

Example fix

// before
--sample-limit "${LIMIT}"  # LIMIT='' 
// after
--sample-limit "${LIMIT:-10}"

const n = Number(value);
if (!Number.isInteger(n)) {
  throw new Error(`--sample-limit must be an integer, got: ${value}`);
}

const isIntStr = (v) => typeof v === 'string' && /^\d+$/.test(v.trim());

try {
  seatunnel.run(args);
} catch (ParameterException e) {
  if (e.getCause() instanceof NumberFormatException) {
    // correct the --sample-limit value and retry
  }
}

When it happens

Trigger: Running `--sample-limit abc`, `--sample-limit 3.5`, `--sample-limit ''`, or a value with stray whitespace/units like `10 rows`.

Common situations: Quoting mistakes in shell scripts that inject empty values; copy-paste with decimal or unit suffixes; YAML/env interpolation producing non-numeric text.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Dry-run mode must not be empty.
• Invalid --status ; expected PENDING, SENDING, ACKED, or DEAD
• --limit must be >= 1
• must be greater than zero.
• must not exceed .

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

Appendix: source

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

                    "--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) {
            MasterType masterType = MasterType.valueOf(value.toUpperCase());
            if (MASTER_TYPE_LIST.contains(masterType)) {
                return masterType;
            } else {

View on GitHub (pinned to cf67b549a7)