apache/seatunnel · error · IllegalArgumentException

Unknown db subcommand

Error message

Unknown db subcommand: ${getSubcommand()}

What it means

DbCommandArgs.buildCommand() resolves the db subcommand name against the DbSubcommand enum; when the name is not null/help and does not match any known CLI name it throws IllegalArgumentException. This guards the CLI parser against unrecognized db subcommands.

Solutions

1. Run `db help` (or omit the subcommand) to list valid subcommands
2. Fix the typo in the CLI invocation (names are kebab-case, e.g. wal-show, wal-list)
3. Check the installed agent version — the subcommand may not exist in that release

Example fix

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

// before running, confirm the subcommand
Set<String> valid = Set.of("help", "wal-list", "wal-show");
if (!valid.contains(subcommand)) { throw new IllegalArgumentException("Unknown: " + subcommand); }

try {
    dbCommandArgs.buildCommand();
} catch (IllegalArgumentException e) {
    printDbHelp();
}

When it happens

Trigger: Invoking the agent CLI with `db <unknown>` where <unknown> is not a registered subcommand (e.g. a typo like `walshow` instead of `wal-show`).

Common situations: Typos in subcommand names; scripts written against an older CLI before a subcommand was renamed or added; guessing subcommand names without running `db help`.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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

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

    @Parameter(
            names = {"--source-id"},
            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;

View on GitHub (pinned to cf67b549a7)