{"record":{"id":"6e14ef1b88c6c513","repo":"apache/seatunnel","slug":"unhandled-subcommand-subcommand","errorCode":null,"errorMessage":"Unhandled subcommand: ${subcommand}","messagePattern":"Unhandled subcommand: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbCommand.java","lineNumber":89,"sourceCode":"                runWalShow(cli.getWalId().longValue());\n                return;\n            case POSITIONS:\n                runPositions(cli.getSourceId());\n                return;\n            case WAL_PURGE_DEAD:\n                runWalPurgeDead();\n                return;\n            case WAL_RETRY_DEAD:\n                runWalRetryDead();\n                return;\n            case WAL_UNSTICK_SENDING:\n                runWalUnstickSending();\n                return;\n            case WAL_PURGE_ACKED:\n                runWalPurgeAcked();\n                return;\n            default:\n                throw new IllegalStateException(\"Unhandled subcommand: \" + subcommand);\n        }\n    }\n\n    private void runInfo() throws Exception {\n        Path db = paths.getSqlitePath();\n        boolean running = paths.agentRunning();\n        System.out.println(\"install-root:  \" + paths.getInstallRoot());\n        System.out.println(\"sqlite-path:   \" + db);\n        System.out.println(\"pid-file:      \" + paths.getPidFile());\n        System.out.println(\"agent-running: \" + running);\n        System.out.println(\"wal-row-ids:   db wal-list  (id column -> wal-show --id)\");\n        printFileSize(\"db-main\", db);\n        printFileSize(\"db-wal\", Paths.get(db.toString() + \"-wal\"));\n        printFileSize(\"db-shm\", Paths.get(db.toString() + \"-shm\"));\n    }\n\n    private void printFileSize(String label, Path path) throws IOException {\n        if (Files.isRegularFile(path)) {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbCommand.java#L71-L107","documentation":"EdgeAgentDbCommand.execute dispatches on the parsed subcommand enum via a switch. If a subcommand value reaches the switch that no case handles, the default branch throws this IllegalStateException. It signals an internal dispatch bug or a newly added enum constant not wired to a handler.","triggerScenarios":"Adding a new DbSubcommand enum constant without adding a corresponding case in execute; a stale/partially deployed binary parsing a subcommand its dispatch table does not know.","commonSituations":"Developer extends the WAL subcommand set but forgets the switch; mixed old/new jars during a hot upgrade where the CLI layer emits a value the command layer cannot handle.","solutions":["Add a case for the missing subcommand in execute() that calls the corresponding runXxx() method.","Rebuild/redeploy the full agent starter jar so enum and switch come from the same build.","Check the exact subcommand string passed on the command line and confirm it maps to an implemented enum constant.","Inspect EdgeAgentDbCommand.execute to see which enum constants fall through to default."],"exampleFix":"// before\ncase WAL_PURGE_ACKED:\n    runWalPurgeAcked();\n    return;\ndefault:\n    throw new IllegalStateException(\"Unhandled subcommand: \" + subcommand);\n// after\ncase WAL_PURGE_ACKED:\n    runWalPurgeAcked();\n    return;\ncase WAL_NEW_SUBCOMMAND:\n    runWalNewSubcommand();\n    return;\ndefault:\n    throw new IllegalStateException(\"Unhandled subcommand: \" + subcommand);","handlingStrategy":"try-catch","validationCode":"// Java: fail fast if the enum has constants the switch does not handle\nstatic void assertAllSubcommandsHandled(DbSubcommand[] values) {\n    Set<DbSubcommand> handled = Set.of(\n        DbSubcommand.INFO, DbSubcommand.WAL_LIST, DbSubcommand.WAL_PURGE_ACKED /* ... */);\n    for (DbSubcommand v : values) {\n        if (!handled.contains(v)) throw new IllegalStateException(\"Unhandled subcommand: \" + v);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    execute(subcommand);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Unhandled subcommand\")) {\n        log.error(\"Dispatch bug: {} is not wired in EdgeAgentDbCommand.execute; rebuild or add a case\", e.getMessage());\n    }\n}","preventionTips":["When adding a DbSubcommand enum constant, add the switch case in execute() in the same commit.","Prefer exhaustive switch expressions (Java 14+) over statement switches so missing cases fail compilation.","Deploy CLI and command layers together from one build; avoid mixed-version jars.","Add a unit test iterating all enum constants through execute() dispatch."],"tags":["cli","dispatch","switch-statement","internal-bug"],"backgroundTag":"internal-invariant-violation","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}