apache/seatunnel · error · IllegalArgumentException

wal-show requires --id <row-id> (run db wal-list; use the…

Error message

wal-show requires --id <row-id> (run db wal-list; use the id column)

What it means

DbCommandArgs.buildCommand() requires the --id option when the resolved subcommand is wal-show, because wal-show cannot identify a WAL row without one. Missing it throws IllegalArgumentException with a hint pointing at db wal-list.

Solutions

1. Add --id <row-id> using an id from the `db wal-list` output
2. Run `db wal-list` first to obtain valid row ids
3. Use `db help` to confirm wal-show's required options

Example fix

// before
db wal-show
// after
db wal-show --id 42

if ("wal-show".equals(subcommand) && id == null) {
    throw new IllegalArgumentException("wal-show requires --id");
}

try {
    dbCommandArgs.buildCommand();
} catch (IllegalArgumentException e) {
    LOG.error("{} — run `db wal-list` to get ids", e.getMessage());
}

When it happens

Trigger: Running `db wal-show` without --id <row-id> (walId == null in buildCommand).

Common situations: Copy-pasting a wal-show example without the id; forgetting that ids come from `db wal-list` output; scripting wal-show before wal-list has produced any rows.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• Unknown db subcommand
• Agent is running (pid file ); stop the agent before write…
• Cluster name is required. Please specify it using -cn or…
• cluster: is not running, Please start the cluster first.
• Dry-run is only supported via CLI

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/ba2be64befca1965. 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/DbCommandArgs.java:87

            description = "Filter source positions")
    private String sourceId;

    @Parameter(
            names = {"--older-than-ms"},
            description = "Cutoff age in ms for wal-purge-acked")
    private long olderThanMs = 0L;

    @Override
    public EdgeAgentCommand<?> buildCommand() {
        if (getSubcommand() == null || "help".equals(getSubcommand())) {
            return new EdgeAgentDbHelpCommand();
        }
        DbSubcommand subcommand = DbSubcommand.fromCliName(getSubcommand());
        if (subcommand == null) {
            throw new IllegalArgumentException("Unknown db subcommand: " + getSubcommand());
        }
        if (subcommand == DbSubcommand.WAL_SHOW && walId == null) {
            throw new IllegalArgumentException(
                    "wal-show requires --id <row-id> (run db wal-list; use the id column)");
        }
        return new EdgeAgentDbCommand(this, subcommand);
    }

    public String getSubcommand() {
        if (commands == null || commands.isEmpty()) {
            return null;
        }
        return commands.get(0);
    }

    public Path getSqlitePathOverride() {
        if (sqlitePath == null || sqlitePath.trim().isEmpty()) {
            return null;
        }
        return Paths.get(sqlitePath.trim());
    }

View on GitHub (pinned to cf67b549a7)