apache/seatunnel · error · IllegalArgumentException

--limit must be >= 1

Error message

--limit must be >= 1

What it means

runWalList validates the --limit option before querying the read-only SQLite connection. A limit below 1 cannot produce a meaningful page of WAL records, so the command rejects it with IllegalArgumentException rather than issuing a query returning nothing or unbounded rows.

Solutions

1. Re-run with --limit set to a positive integer, e.g. --limit 20.
2. Fix the shell script default so an unset variable yields a positive value: LIMIT=${LIMIT:-50}.
3. If you intended unlimited rows, use the largest sensible positive value; the CLI requires an explicit positive limit.

Example fix

// before (script)
agent db wal-list --limit ${LIMIT}
// after (script)
LIMIT=${LIMIT:-50}
agent db wal-list --limit ${LIMIT}

limit = int(raw_limit) if raw_limit else 50
if limit < 1:
    raise ValueError('--limit must be >= 1')
subprocess.run(['agent', 'db', 'wal-list', '--limit', str(limit)], check=True)

try:
    run_wal_list(limit)
except subprocess.CalledProcessError as e:
    if '--limit must be >= 1' in e.stderr:
        print('Fix the --limit value; it must be a positive integer')

When it happens

Trigger: Running `agent db wal-list` with --limit 0 or a negative number; a script passing a computed limit that evaluates to 0.

Common situations: Shell variable defaults to 0 when unset; users confuse 'limit 0 = all rows' semantics from other tools with this CLI's requirement of limit >= 1.

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

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

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

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbCommand.java:155

                    any = true;
                    long updatedAt = rs.getLong("oldest_updated_at");
                    System.out.printf(
                            Locale.ROOT,
                            "  %-8s %s (%d ms ago)%n",
                            rs.getString("status"),
                            formatTime(updatedAt),
                            ageMs(updatedAt));
                }
                if (!any) {
                    System.out.println("  (empty)");
                }
            }
        }
    }

    private void runWalList(String status, int limit) throws Exception {
        if (limit < 1) {
            throw new IllegalArgumentException("--limit must be >= 1");
        }
        if (status != null) {
            validateWalStatus(status);
        }

        try (EdgeAgentDbConnection db = EdgeAgentDbConnection.openReadOnly(paths.getSqlitePath())) {
            try (PreparedStatement statement =
                    db.getConnection().prepareStatement(EdgeAgentDbSql.WAL_LIST)) {
                statement.setString(1, status);
                statement.setString(2, status);
                statement.setInt(3, limit);
                try (ResultSet rs = statement.executeQuery()) {
                    System.out.printf(
                            Locale.ROOT,
                            "%8s %10s %-8s %7s %24s %12s %8s%n",
                            "id(pk)",
                            "batch_id",
                            "status",

View on GitHub (pinned to cf67b549a7)