{"record":{"id":"5dc95bac582278c9","repo":"quarkusio/quarkus","slug":"unable-to-find-or-load-top-command-classname","errorCode":null,"errorMessage":"Unable to find or load top command: <className>","messagePattern":"Unable to find or load top command: <className>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java","lineNumber":101,"sourceCode":"\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":83,"sourceCodeEnd":105,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java#L83-L105","documentation":"Thrown by DefaultAeshRuntimeRunnerFactory.loadCommand() when the configured top command class cannot be found, loaded, or instantiated (ClassNotFoundException, missing no-arg constructor, instantiation failure). The original exception is wrapped as the cause.","triggerScenarios":"loadCommand() is called by resolveTopCommand(); any exception other than the IllegalStateException from error 521 — e.g. ClassNotFoundException from loadClass, NoSuchMethodException from getConstructor(), or ReflectiveOperationException from newInstance() — triggers this message with the className attached.","commonSituations":"Typo in the quarkus.aesh.top-command class name; command class excluded from the native image or not on the runtime classpath; command class has no public no-arg constructor and is not a CDI bean.","solutions":["Fix quarkus.aesh.top-command (or the build-time detected class) to a valid, fully-qualified class name present on the runtime classpath.","Ensure the command class has a public no-argument constructor, or register it as a CDI bean so Arc can resolve it.","If building a native image, verify the command class is not excluded and its constructor is registered for reflection."],"exampleFix":"// before\nquarkus.aesh.top-command=com.acme.HelloComand // typo -> ClassNotFoundException\n// after\nquarkus.aesh.top-command=com.acme.HelloCommand // public no-arg ctor, on classpath","handlingStrategy":"validation","validationCode":"String cls = ConfigProvider.getConfig().getValue(\"quarkus.aesh.top-command\", String.class);\ntry { Class.forName(cls, false, Thread.currentThread().getContextClassLoader()); }\ncatch (ClassNotFoundException e) { throw new IllegalStateException(\"Top command class not on classpath: \" + cls); }","typeGuard":null,"tryCatchPattern":"try { runnerFactory.create(); } catch (IllegalStateException e) { if (e.getMessage().startsWith(\"Unable to find or load top command\")) { log.error(\"Check class name spelling and no-arg constructor\", e.getCause()); } throw e; }","preventionTips":["Copy fully-qualified class names from the source file, never by hand.","Give command classes a public no-arg constructor or register them as CDI beans.","For native builds, confirm the command class survives native compilation."],"tags":["quarkus","aesh","cli","classpath","reflection"],"backgroundTag":"classnotfound","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"}