quarkusio/quarkus · critical · IllegalStateException

Handler '${handlerClassName}' has not been properly configur

Error message

Handler '${handlerClassName}' has not been properly configured.

What it means

At runtime startup, Quarkus REST iterates all registered GenericRuntimeConfigurableServerRestHandler instances and looks up a configuration Supplier in the runtime config map produced at deployment. If no supplier was recorded for a handler's configuration class, the handler cannot be wired and startup fails with IllegalStateException.

Source

Thrown at extensions/resteasy-reactive/rest/runtime/src/main/java/io/quarkus/resteasy/reactive/server/runtime/ResteasyReactiveRuntimeRecorder.java:68

        deployment.getValue().setRuntimeConfiguration(runtimeConfiguration);

        return new Supplier<>() {
            @Override
            public RuntimeConfiguration get() {
                return runtimeConfiguration;
            }
        };
    }

    @SuppressWarnings({ "unchecked", "rawtypes", "ForLoopReplaceableByForEach" })
    public void configureHandlers(RuntimeValue<Deployment> deployment, Map<String, Supplier<?>> runtimeConfigMap) {
        List<GenericRuntimeConfigurableServerRestHandler<?>> runtimeConfigurableServerRestHandlers = deployment.getValue()
                .getRuntimeConfigurableServerRestHandlers();
        for (int i = 0; i < runtimeConfigurableServerRestHandlers.size(); i++) {
            GenericRuntimeConfigurableServerRestHandler handler = runtimeConfigurableServerRestHandlers.get(i);
            Supplier<?> supplier = runtimeConfigMap.get(handler.getConfigurationClass().getName());
            if (supplier == null) {
                throw new IllegalStateException(
                        "Handler '" + handler.getClass().getName() + "' has not been properly configured.");
            }
            handler.configure(supplier.get());
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Align all Quarkus extension versions with the platform BOM (run ./mvnw quarkus:update or fix the quarkus.platform.version)
Clean rebuild the application to eliminate stale build artifacts
Check which handler class is named in the message and report/upgrade the owning extension
If writing an extension, ensure the deployment step records the config supplier under the handler's configuration class name

Defensive patterns

Strategy: validation

Validate before calling

// fail fast at startup: verify every handler has a config supplier
for (var handler : handlers) {
    if (!runtimeConfigMap.containsKey(handler.getConfigurationClass().getName())) {
        throw new IllegalStateException("Missing runtime config for " + handler.getClass().getName());
    }
}

Prevention

Keep all Quarkus extension versions aligned with the platform BOM
Clean rebuild when adding/removing extensions
If authoring an extension, always record the config supplier for each registered handler

When it happens

Trigger: An extension registers a runtime-configurable server REST handler in deployment but never produces the matching runtime configuration entry (runtimeConfigMap) for handler.getConfigurationClass().getName(); typically a broken/incompatible extension version mismatch between deployment and runtime.

Common situations: Mixing Quarkus versions (e.g. an extension built against a different Quarkus release); a custom handler added by an extension without recording its config supplier; corrupted incremental build state.

Related errors

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