apache/seatunnel · error · IllegalArgumentException

Invalid --status ${status}; expected PENDING, SENDING, ACKED

Error message

Invalid --status ${status}; expected PENDING, SENDING, ACKED, or DEAD

What it means

runWalList accepts an optional --status filter that must be one of the WalRecordStatus enum values. validateWalStatus attempts WalRecordStatus.valueOf and converts failure into an IllegalArgumentException listing the four accepted values, chaining the original exception for diagnostics.

Source

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

        }
    }

    private long countByStatus(EdgeAgentDbConnection db, String sql, String status)
            throws SQLException {
        try (PreparedStatement statement = db.getConnection().prepareStatement(sql)) {
            statement.setString(1, status);
            try (ResultSet rs = statement.executeQuery()) {
                rs.next();
                return rs.getLong(1);
            }
        }
    }

    private void validateWalStatus(String status) {
        try {
            WalRecordStatus.valueOf(status);
        } catch (IllegalArgumentException ex) {
            throw new IllegalArgumentException(
                    "Invalid --status " + status + "; expected PENDING, SENDING, ACKED, or DEAD",
                    ex);
        }
    }

    private static String formatTime(long epochMs) {
        return TIME_FMT.format(Instant.ofEpochMilli(epochMs));
    }

    private static long ageMs(long epochMs) {
        return Math.max(0L, System.currentTimeMillis() - epochMs);
    }

    private static String nullToDash(String value) {
        return value == null ? "-" : value;
    }

    private static String previewUtf8(byte[] bytes) {

View on GitHub (pinned to cf67b549a7)

Solutions

Use an exact uppercase match: --status PENDING, SENDING, ACKED, or DEAD.
Trim whitespace and normalize case in the calling script before passing the value.
Validate against the allowed list in wrapper scripts before invoking the CLI.
Consult the WalRecordStatus enum for the authoritative set of statuses.

Example fix

// before
agent db wal-list --status acked
// after
agent db wal-list --status ACKED

Defensive patterns

Strategy: validation

Validate before calling

VALID = {'PENDING','SENDING','ACKED','DEAD'}
if status is not None:
    status = status.strip().upper()
    if status not in VALID:
        raise ValueError(f'Invalid --status {status}; expected PENDING, SENDING, ACKED, or DEAD')

Try / catch

try {
  runWalList(status, limit);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid --status")) {
    System.err.println("Use one of: PENDING, SENDING, ACKED, DEAD (uppercase)");
  }
}

Prevention

Normalize case and trim whitespace before passing --status.
Keep status values in sync with the WalRecordStatus enum; never invent new names.
Source the status from a fixed whitelist in wrapper scripts.

When it happens

Trigger: Running wal-list --status with a value other than PENDING, SENDING, ACKED, or DEAD (e.g. lowercase 'acked', 'failed', 'done', or values with trailing whitespace).

Common situations: Users pass lowercase status names; scripts pass statuses from other systems ('dead-letter', 'sent'); typos such as 'PENDNG'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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