quarkusio/quarkus · critical · RuntimeException

Singleton for ${className} not found.

Error message

Singleton for ${className} not found.

What it means

SingletonBeanFactory creates per-request bean instances from a singleton registry. At build time Quarkus registers the singleton class name; if createInstance() is called for a class that was never registered, the lookup in the static INSTANCES map returns null and this RuntimeException is thrown.

Source

Thrown at independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/core/SingletonBeanFactory.java:30

    private String className;

    public SingletonBeanFactory(String className) {
        this.className = className;
    }

    public SingletonBeanFactory() {
    }

    @Override
    public String toString() {
        return "SingletonBeanFactory[" + className + "]";
    }

    @Override
    public BeanInstance<T> createInstance() {
        Object instance = INSTANCES.get(className);
        if (instance == null) {
            throw new RuntimeException("Singleton for " + className + " not found.");
        }
        return new BeanInstance<T>() {
            @Override
            public T getInstance() {
                return (T) instance;
            }

            @Override
            public void close() {

            }
        };
    }

    public String getClassName() {
        return className;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the class is registered as a singleton (it was created via the factory's register/create path at startup before createInstance is called)
2. Check that the className used for lookup matches exactly (fully qualified name) the one used at registration
3. Ensure the class is included in the native image / build scanning (add @Path/@Provider or register it explicitly)
4. Rebuild the application so build-time registration steps run for the missing class

Example fix

// before
BeanInstance<MyResource> bi = new SingletonBeanFactory<>(MyResource.class.getName()).createInstance(); // throws if never registered
// after
SingletonBeanFactory<MyResource> factory = new SingletonBeanFactory<>(MyResource.class.getName());
factory.registerInstance(new MyResource()); // ensure registration happens first
BeanInstance<MyResource> bi = factory.createInstance();

if (!SingletonBeanFactory.hasInstance(className)) { throw new IllegalStateException("Register singleton " + className + " before createInstance()"); }

try {
    BeanInstance<T> bi = factory.createInstance();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("not found")) {
        throw new IllegalStateException("Singleton was never registered: check build-time scanning/registration", e);
    }
    throw e;
}

When it happens

Trigger: Calling createInstance() when the class name was not registered in INSTANCES beforehand (e.g. the resource/provider class was not processed at build time, or the singleton was created with a different className key than the lookup key).

Common situations: Custom resource or provider classes not being discovered during the build, build-time/runtime class-name mismatch, using the factory manually to instantiate a class Quarkus never registered.

Related errors

• Unable to determine if bean '${className}' is available
• Security annotation placed on resource method '${className}#
• Unable to create class '{targetClassName}'. To fix the probl
• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.

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