{"record":{"id":"27f89d2e4e1a2a69","repo":"elastic/elasticsearch","slug":"usage-27f89d","errorCode":"USAGE","errorMessage":"Unknown command [${subcommandName}]","messagePattern":"Unknown command \\[(.+?)\\]","errorType":"validation","errorClass":"UserException","httpStatus":null,"severity":"error","filePath":"libs/cli/src/main/java/org/elasticsearch/cli/MultiCommand.java","lineNumber":89,"sourceCode":"        println.accept(\"\");\n    }\n\n    @Override\n    protected void execute(Terminal terminal, OptionSet options, ProcessInfo processInfo) throws Exception {\n        if (subcommands.isEmpty()) {\n            throw new IllegalStateException(\"No subcommands configured\");\n        }\n\n        // .values(...) returns an unmodifiable list\n        final List<String> args = new ArrayList<>(arguments.values(options));\n        if (args.isEmpty()) {\n            throw new MissingCommandException();\n        }\n\n        String subcommandName = args.remove(0);\n        Command subcommand = subcommands.get(subcommandName);\n        if (subcommand == null) {\n            throw new UserException(ExitCodes.USAGE, \"Unknown command [\" + subcommandName + \"]\");\n        }\n\n        for (final KeyValuePair pair : this.settingOption.values(options)) {\n            args.add(\"-E\" + pair);\n        }\n\n        subcommand.mainWithoutErrorHandling(args.toArray(new String[0]), terminal, processInfo);\n    }\n\n    @Override\n    public void close() throws IOException {\n        IOUtils.close(subcommands.values());\n    }\n\n    static final class MissingCommandException extends UserException {\n        MissingCommandException() {\n            super(ExitCodes.USAGE, \"Missing required command\");\n        }","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/cli/src/main/java/org/elasticsearch/cli/MultiCommand.java#L71-L107","documentation":"Thrown by MultiCommand.execute when the first positional argument does not match any key in the configured `subcommands` map. MultiCommand is the base class for CLI tools that dispatch to subcommands (e.g. `elasticsearch-keystore`, `elasticsearch-plugin`); each subcommand registers its name, and an unknown name is a usage error. Exit code USAGE indicates the user invoked the tool wrong, not that anything is broken.","triggerScenarios":"Typing `elasticsearch-plugin instal x-pack` instead of `install`. Using a subcommand name from a different version. Forgetting the subcommand entirely so the first token is parsed as a subcommand name.","commonSituations":"Auto-complete typo. Copy-pasting a command from docs for a different version. Misremembering verb forms (e.g. `list` vs `ls`).","solutions":["Run the tool with no arguments or `--help` to list valid subcommands.","Correct the spelling to match a registered subcommand exactly (case-sensitive).","If the subcommand should exist, verify you are on the version that introduced it."],"exampleFix":"// before\nbin/elasticsearch-plugin instal analysis-icu\n// after\nbin/elasticsearch-plugin install analysis-icu\n// list valid subcommands\nbin/elasticsearch-plugin --help","handlingStrategy":"validation","validationCode":"Set<String> valid = cli.subcommandNames(); // expose the registered names\nif (!valid.contains(requestedSub)) {\n    throw new IllegalArgumentException(\"Unknown subcommand \" + requestedSub + \"; valid: \" + valid);\n}","typeGuard":"static boolean isKnownSubcommand(MultiCommand cli, String name) {\n    return cli.getSubcommands().containsKey(name);\n}","tryCatchPattern":"try {\n    cli.main(args);\n} catch (UserException e) {\n    if (e.exitCode == ExitCodes.USAGE && e.getMessage().startsWith(\"Unknown command\")) {\n        // print help with the registered subcommands and exit\n    } else throw e;\n}","preventionTips":["Always expose `--help`/`-h` from your MultiCommand subclass to enumerate valid subcommands.","Validate the first token against the subcommands map before dispatch.","Document the subcommand list in the tool's manpage."],"tags":["cli","multi-command","usage","arguments","dispatch"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}