{"record":{"id":"605a29b97534fc40","repo":"quarkusio/quarkus","slug":"top-command-must-implement-org-aesh-command-comman","errorCode":null,"errorMessage":"Top command must implement org.aesh.command.Command interface: <className>","messagePattern":"Top command must implement org\\.aesh\\.command\\.Command interface: <className>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java","lineNumber":89,"sourceCode":"            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\n        return null;\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private Command<?> loadCommand(String className) {\n        try {\n            Class<?> commandClass = Thread.currentThread().getContextClassLoader().loadClass(className);\n            if (!Command.class.isAssignableFrom(commandClass)) {\n                throw new IllegalStateException(\n                        \"Top command must implement org.aesh.command.Command interface: \" + className);\n            }\n            var handle = Arc.container().instance(commandClass);\n            if (handle.isAvailable()) {\n                return (Command<?>) handle.get();\n            }\n            // Not a CDI bean — fall back to direct instantiation\n            return (Command<?>) commandClass.getConstructor().newInstance();\n        } catch (IllegalStateException e) {\n            throw e;\n        } catch (Exception e) {\n            throw new IllegalStateException(\"Unable to find or load top command: \" + className, e);\n        }\n    }\n}\n","sourceCodeStart":71,"sourceCodeEnd":105,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java#L71-L105","documentation":"Thrown by DefaultAeshRuntimeRunnerFactory.loadCommand() when the class configured as top command (via quarkus.aesh.top-command or build-time detection) loads successfully but does not implement org.aesh.command.Command. The runner requires an actual AESH Command instance.","triggerScenarios":"loadCommand() is invoked by resolveTopCommand() with a class name; Thread.getContextClassLoader().loadClass(className) succeeds, but Command.class.isAssignableFrom(commandClass) is false, so an IllegalStateException with the offending className is thrown.","commonSituations":"Typing a wrong fully-qualified class name in quarkus.aesh.top-command (a class that exists but is not a Command); pointing the property at a helper/POJO class; refactoring that moved the Command interface off the class.","solutions":["Make the configured class implement org.aesh.command.Command (with @CommandDefinition).","Correct quarkus.aesh.top-command to point at the class that actually implements Command."],"exampleFix":"// before\nquarkus.aesh.top-command=com.acme.cli.Util\n// after\nquarkus.aesh.top-command=com.acme.cli.HelloCommand // implements org.aesh.command.Command","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(\"com.acme.cli.HelloCommand\");\nif (!org.aesh.command.Command.class.isAssignableFrom(c)) {\n    throw new IllegalStateException(\"top command must implement org.aesh.command.Command\");\n}","typeGuard":"static boolean isAeshCommand(String className) {\n    try { return org.aesh.command.Command.class.isAssignableFrom(Class.forName(className)); }\n    catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try { runnerFactory.create(); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"Top command must implement\")) { log.error(\"Fix quarkus.aesh.top-command to point at a Command implementation\"); } throw e; }","preventionTips":["Point quarkus.aesh.top-command only at classes implementing org.aesh.command.Command.","Prefer @CommandDefinition detection over manual class-name configuration."],"tags":["quarkus","aesh","cli","type-mismatch","configuration"],"backgroundTag":"class-does-not-implement-interface","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}