{"record":{"id":"5fbb522a60b1f369","repo":"quarkusio/quarkus","slug":"please-add-the-quarkus-security-extension","errorCode":null,"errorMessage":"Please add the `quarkus-security` extension","messagePattern":"Please add the `quarkus-security` extension","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpSecurityProcessor.java","lineNumber":328,"sourceCode":"            bytecodeTransformerProducer\n                    .produce(new BytecodeTransformerBuildItem(CSRF.class.getName(), (cls, classVisitor) -> {\n                        var classTransformer = new ClassTransformer(cls);\n                        classTransformer.removeMethod(\"builder\", CSRF.Builder.class);\n                        try (var mc = classTransformer.addMethod(\"builder\", CSRF.Builder.class)) {\n                            mc.setModifiers(ACC_PUBLIC | ACC_STATIC);\n                            if (capabilities.isPresent(Capability.SECURITY)) {\n                                // static Builder builder() {\n                                //     return new io.quarkus.something.CsfrBuilder();\n                                // }\n                                var builderInstance = mc.newInstance(MethodDescriptor.ofConstructor(csrfBuilderClass));\n                                mc.returnValue(mc.checkCast(builderInstance, CSRF.Builder.class));\n                            } else {\n                                // static Builder builder() {\n                                //     throw new IllegalStateException(\"Please add the `quarkus-security` extension\");\n                                // }\n                                mc.throwException(IllegalStateException.class, \"Please add the `quarkus-security` extension\");\n                            }\n                        }\n                        return classTransformer.applyTo(classVisitor);\n                    }));\n        }\n    }\n\n    @Consume(TlsRegistryBuildItem.class) // we may need to register a TLS configuration for the mTLS\n    @Produce(PreRouterFinalizationBuildItem.class)\n    @Record(ExecutionTime.RUNTIME_INIT)\n    @BuildStep\n    HttpSecurityConfigSetupCompleteBuildItem initializeHttpSecurity(\n            Optional<HttpAuthenticationHandlerBuildItem> authenticationHandler,\n            HttpSecurityRecorder recorder, BeanContainerBuildItem beanContainerBuildItem,\n            ShutdownContextBuildItem shutdown) {\n        if (authenticationHandler.isPresent()) {\n            RuntimeValue<CORSConfig> programmaticCorsConfig = recorder.prepareHttpSecurityConfiguration(shutdown);\n            recorder.initializeHttpAuthenticatorHandler(authenticationHandler.get().handler, beanContainerBuildItem.getValue());\n            return new HttpSecurityConfigSetupCompleteBuildItem(programmaticCorsConfig);\n        }","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpSecurityProcessor.java#L310-L346","documentation":"HttpSecurityProcessor prepares a CSRF token builder class but only if the quarkus-security runtime classes are present. When CSRF handling is needed without the quarkus-security extension on the classpath, the generated builder is transformed to throw IllegalStateException('Please add the `quarkus-security` extension') instead of silently misbehaving.","triggerScenarios":"An application uses features that require the CSRF token builder (e.g. quarkus-vertx-http CSRF support) at runtime but quarkus-security is not a dependency; the bytecode-recorded builder throws when invoked.","commonSituations":"Adding vertx-http or form-auth related extensions without quarkus-security; removing quarkus-security in a dependency cleanup while still enabling CSRF; relying on a transitive dependency that got dropped in a version upgrade.","solutions":["Add the quarkus-security dependency (io.quarkus:quarkus-security) to the application","Re-run the build so the security processor wires the real CSRF builder","If CSRF is not needed, disable the CSRF feature that triggers this code path"],"exampleFix":"// before (pom.xml)\n<dependency>io.quarkus:quarkus-vertx-http</dependency>\n\n// after\n<dependency>io.quarkus:quarkus-vertx-http</dependency>\n<dependency>io.quarkus:quarkus-security</dependency>","handlingStrategy":"fallback","validationCode":"boolean hasSecurity = Class.forName(\"io.quarkus.security.identity.SecurityIdentity\", false,\n    Thread.currentThread().getContextClassLoader()) != null;\nif (!hasSecurity && csrfEnabled) {\n    throw new IllegalStateException(\"CSRF requires the quarkus-security extension\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    csrfBuilder.build();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"quarkus-security\")) {\n        throw new IllegalStateException(\"Add io.quarkus:quarkus-security to your pom.xml\", e);\n    }\n    throw e;\n}","preventionTips":["Declare quarkus-security explicitly whenever CSRF or form auth is used","Avoid relying on transitive extension dependencies for security features","Run a build with -Dquarkus.bootstrap.enabled checks to catch missing security wiring early"],"tags":["security","csrf","missing-dependency"],"backgroundTag":"missing-extension-dependency","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"}