{"record":{"id":"3fbe6a89700f8155","repo":"quarkusio/quarkus","slug":"singleton-for-classname-not-found","errorCode":null,"errorMessage":"Singleton for ${className} not found.","messagePattern":"Singleton for (.+?) not found\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/core/SingletonBeanFactory.java","lineNumber":30,"sourceCode":"    private String className;\n\n    public SingletonBeanFactory(String className) {\n        this.className = className;\n    }\n\n    public SingletonBeanFactory() {\n    }\n\n    @Override\n    public String toString() {\n        return \"SingletonBeanFactory[\" + className + \"]\";\n    }\n\n    @Override\n    public BeanInstance<T> createInstance() {\n        Object instance = INSTANCES.get(className);\n        if (instance == null) {\n            throw new RuntimeException(\"Singleton for \" + className + \" not found.\");\n        }\n        return new BeanInstance<T>() {\n            @Override\n            public T getInstance() {\n                return (T) instance;\n            }\n\n            @Override\n            public void close() {\n\n            }\n        };\n    }\n\n    public String getClassName() {\n        return className;\n    }\n","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/common/core/SingletonBeanFactory.java#L12-L48","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the class is registered as a singleton (it was created via the factory's register/create path at startup before createInstance is called)","Check that the className used for lookup matches exactly (fully qualified name) the one used at registration","Ensure the class is included in the native image / build scanning (add @Path/@Provider or register it explicitly)","Rebuild the application so build-time registration steps run for the missing class"],"exampleFix":"// before\nBeanInstance<MyResource> bi = new SingletonBeanFactory<>(MyResource.class.getName()).createInstance(); // throws if never registered\n// after\nSingletonBeanFactory<MyResource> factory = new SingletonBeanFactory<>(MyResource.class.getName());\nfactory.registerInstance(new MyResource()); // ensure registration happens first\nBeanInstance<MyResource> bi = factory.createInstance();","handlingStrategy":"validation","validationCode":"if (!SingletonBeanFactory.hasInstance(className)) { throw new IllegalStateException(\"Register singleton \" + className + \" before createInstance()\"); }","typeGuard":null,"tryCatchPattern":"try {\n    BeanInstance<T> bi = factory.createInstance();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"not found\")) {\n        throw new IllegalStateException(\"Singleton was never registered: check build-time scanning/registration\", e);\n    }\n    throw e;\n}","preventionTips":["Always register the singleton instance before any createInstance call","Use exact fully-qualified class names for both register and lookup","Verify the class is discovered at build time (annotation present or explicit registration)","Rebuild after adding new resources/providers so build steps run"],"tags":["quarkus","resteasy-reactive","cdi","singleton","classloading"],"backgroundTag":"singleton-not-registered","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"}