{"record":{"id":"7317fce4487e21b7","repo":"quarkusio/quarkus","slug":"unable-to-find-top-command-ensure-you-have-a-com","errorCode":null,"errorMessage":"Unable to find top command. Ensure you have a @CommandDefinition class or set the quarkus.aesh.top-command property.","messagePattern":"Unable to find top command\\. Ensure you have a @CommandDefinition class or set the quarkus\\.aesh\\.top-command property\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java","lineNumber":62,"sourceCode":"            AeshRuntimeRunner runner = AeshRuntimeRunner.builder()\n                    .containerBuilder(new AeshCdiCommandContainerBuilder<>())\n                    .command(commandInstance);\n            if (settings.commandInvocationProvider() != null) {\n                runner.commandInvocationProvider(\n                        (org.aesh.command.invocation.CommandInvocationProvider<?>) settings.commandInvocationProvider());\n            }\n            if (settings.converterInvocationProvider() != null) {\n                runner.converterInvocationProvider(settings.converterInvocationProvider());\n            }\n            if (settings.validatorInvocationProvider() != null) {\n                runner.validatorInvocationProvider(settings.validatorInvocationProvider());\n            }\n            if (defaultValueProvider.isResolvable()) {\n                runner.defaultValueProvider(defaultValueProvider.get());\n            }\n            return runner;\n        }\n        throw new IllegalStateException(\n                \"Unable to find top command. Ensure you have a @CommandDefinition class \"\n                        + \"or set the quarkus.aesh.top-command property.\");\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private Command<?> resolveTopCommand() {\n        // 1. Explicit config property overrides everything\n        if (configuration.topCommand().isPresent()) {\n            String topCommandName = configuration.topCommand().get();\n            return loadCommand(topCommandName);\n        }\n\n        // 2. Use the build-time detected top command\n        String topClassName = aeshContext.getTopCommandClassName();\n        if (topClassName != null) {\n            return loadCommand(topClassName);\n        }\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java#L44-L80","documentation":"The Quarkus AESH extension builds a CLI runner but found no top-level command to execute. The factory first honors quarkus.aesh.top-command, then the build-time detected @CommandDefinition class; when neither yields a command it fails fast with this IllegalStateException at application startup.","triggerScenarios":"DefaultAeshRuntimeRunnerFactory.create() runs at startup when resolveTopCommand() returns null: quarkus.aesh.top-command is unset AND no class annotated with @CommandDefinition was discovered at build time.","commonSituations":"Adding the quarkus-aesh extension but never defining a CLI command; misspelling or omitting @CommandDefinition; expecting the extension to work without any command class.","solutions":["Annotate a class implementing org.aesh.command.Command with @CommandDefinition(name=..., description=...) so it is detected as the top command.","Or set quarkus.aesh.top-command=<fully.qualified.ClassName> in application.properties pointing at an existing Command implementation."],"exampleFix":"// before\npublic class HelloCommand { /* no annotation, not a Command */ }\n// after\n@CommandDefinition(name = \"hello\", description = \"Says hello\")\npublic class HelloCommand implements Command<CommandResult> {\n    public CommandResult execute(CommandInvocation ci) { ... }\n}","handlingStrategy":"validation","validationCode":"if (ConfigProvider.getConfig().getOptionalValue(\"quarkus.aesh.top-command\", String.class).isEmpty()) {\n    // ensure exactly one class is annotated @CommandDefinition and implements org.aesh.command.Command\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always ship at least one @CommandDefinition-annotated Command class with the aesh extension.","Set quarkus.aesh.top-command explicitly when the top command is ambiguous or built dynamically."],"tags":["quarkus","aesh","cli","startup","configuration"],"backgroundTag":"missing-cli-command","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}