{"record":{"id":"10c0fef7f778b4bc","repo":"quarkusio/quarkus","slug":"failed-to-register-command-classname","errorCode":null,"errorMessage":"Failed to register command: <className>","messagePattern":"Failed to register command: <className>","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultCliCommandRegistryFactory.java","lineNumber":65,"sourceCode":"            builder.defaultValueProvider(defaultValueProvider.get());\n        }\n\n        // Collect all subcommand class names so we only register top-level commands.\n        // Subcommands are registered by aesh when processing their parent group.\n        Set<String> subCommandClasses = new HashSet<>();\n        for (AeshCommandMetadata meta : aeshContext.getCommands()) {\n            subCommandClasses.addAll(meta.getSubCommandClassNames());\n        }\n\n        for (Command command : commands) {\n            String className = unwrapClassName(command);\n            if (subCommandClasses.contains(className)) {\n                continue;\n            }\n            try {\n                builder.command(command);\n            } catch (Exception e) {\n                throw new RuntimeException(\n                        \"Failed to register command: \" + className, e);\n            }\n        }\n\n        return builder;\n    }\n\n    /**\n     * Unwrap CDI proxy class names to get the actual bean class name.\n     */\n    private static String unwrapClassName(Object bean) {\n        if (bean instanceof ClientProxy) {\n            return bean.getClass().getSuperclass().getName();\n        }\n        return bean.getClass().getName();\n    }\n}\n","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultCliCommandRegistryFactory.java#L47-L83","documentation":"DefaultCliCommandRegistryFactory.create() registers each discovered command (including subcommands) into an AESH CommandBuilder via builder.command(command). If AESH rejects a command — e.g. invalid @CommandDefinition metadata or duplicate registration — the failure is wrapped in a RuntimeException naming the offending class.","triggerScenarios":"During registry creation, builder.command(command) throws for a specific className (command not in subCommandClasses); the exception is rethrown as \"Failed to register command: <className>\" with the cause attached.","commonSituations":"Two command classes with the same @CommandDefinition name; malformed @CommandDefinition (empty name); AESH validation rejecting a command's option definitions.","solutions":["Inspect the wrapped cause to see why AESH rejected the class named in the message.","Ensure each @CommandDefinition has a unique, non-empty name across the application.","Fix invalid option/argument annotations on the failing command class."],"exampleFix":"// before\n@CommandDefinition(name = \"run\", ...)\npublic class A implements Command<CommandResult> { ... }\n@CommandDefinition(name = \"run\", ...)\npublic class B implements Command<CommandResult> { ... } // duplicate name\n// after\n@CommandDefinition(name = \"run-a\", ...)\npublic class A implements Command<CommandResult> { ... }\n@CommandDefinition(name = \"run-b\", ...)\npublic class B implements Command<CommandResult> { ... }","handlingStrategy":"try-catch","validationCode":"Set<String> seen = new HashSet<>();\nfor (Class<?> c : commandClasses) {\n    String name = c.getAnnotation(CommandDefinition.class).name();\n    if (!seen.add(name)) throw new IllegalStateException(\"Duplicate command name: \" + name);\n}","typeGuard":null,"tryCatchPattern":"try { registryFactory.create(); } catch (RuntimeException e) { log.error(\"Command registration failed: \" + e.getMessage(), e.getCause()); throw e; }","preventionTips":["Keep @CommandDefinition names unique across all commands and subcommands.","Read the wrapped cause — AESH reports the exact validation that failed."],"tags":["quarkus","aesh","cli","command-registry","duplicate"],"backgroundTag":"command-registration-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}