What causes "Unable to find or load top command: " in quarkusio/quarkus?

Fix quarkus.aesh.top-command (or the build-time detected class) to a valid, fully-qualified class name present on the runtime classpath.

quarkusio/quarkus · error · IllegalStateException

Unable to find or load top command: <className>

Error message

Unable to find or load top command: <className>

What it means

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.

Source

Thrown at extensions/aesh/runtime/src/main/java/io/quarkus/aesh/runtime/DefaultAeshRuntimeRunnerFactory.java:101

    @SuppressWarnings("unchecked")
    private Command<?> loadCommand(String className) {
        try {
            Class<?> commandClass = Thread.currentThread().getContextClassLoader().loadClass(className);
            if (!Command.class.isAssignableFrom(commandClass)) {
                throw new IllegalStateException(
                        "Top command must implement org.aesh.command.Command interface: " + className);
            }
            var handle = Arc.container().instance(commandClass);
            if (handle.isAvailable()) {
                return (Command<?>) handle.get();
            }
            // Not a CDI bean — fall back to direct instantiation
            return (Command<?>) commandClass.getConstructor().newInstance();
        } catch (IllegalStateException e) {
            throw e;
        } catch (Exception e) {
            throw new IllegalStateException("Unable to find or load top command: " + className, e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

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.

Example fix

// before
quarkus.aesh.top-command=com.acme.HelloComand // typo -> ClassNotFoundException
// after
quarkus.aesh.top-command=com.acme.HelloCommand // public no-arg ctor, on classpath

Defensive patterns

Strategy: validation

Validate before calling

String cls = ConfigProvider.getConfig().getValue("quarkus.aesh.top-command", String.class);
try { Class.forName(cls, false, Thread.currentThread().getContextClassLoader()); }
catch (ClassNotFoundException e) { throw new IllegalStateException("Top command class not on classpath: " + cls); }

Try / catch

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; }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/5dc95bac582278c9. Report an issue: GitHub.