What causes "Please add the `quarkus-security` extension" in quarkusio/quarkus?

Add the quarkus-security dependency (io.quarkus:quarkus-security) to the application

quarkusio/quarkus · error · IllegalStateException

Please add the `quarkus-security` extension

Error message

Please add the `quarkus-security` extension

What it means

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.

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpSecurityProcessor.java:328

            bytecodeTransformerProducer
                    .produce(new BytecodeTransformerBuildItem(CSRF.class.getName(), (cls, classVisitor) -> {
                        var classTransformer = new ClassTransformer(cls);
                        classTransformer.removeMethod("builder", CSRF.Builder.class);
                        try (var mc = classTransformer.addMethod("builder", CSRF.Builder.class)) {
                            mc.setModifiers(ACC_PUBLIC | ACC_STATIC);
                            if (capabilities.isPresent(Capability.SECURITY)) {
                                // static Builder builder() {
                                //     return new io.quarkus.something.CsfrBuilder();
                                // }
                                var builderInstance = mc.newInstance(MethodDescriptor.ofConstructor(csrfBuilderClass));
                                mc.returnValue(mc.checkCast(builderInstance, CSRF.Builder.class));
                            } else {
                                // static Builder builder() {
                                //     throw new IllegalStateException("Please add the `quarkus-security` extension");
                                // }
                                mc.throwException(IllegalStateException.class, "Please add the `quarkus-security` extension");
                            }
                        }
                        return classTransformer.applyTo(classVisitor);
                    }));
        }
    }

    @Consume(TlsRegistryBuildItem.class) // we may need to register a TLS configuration for the mTLS
    @Produce(PreRouterFinalizationBuildItem.class)
    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    HttpSecurityConfigSetupCompleteBuildItem initializeHttpSecurity(
            Optional<HttpAuthenticationHandlerBuildItem> authenticationHandler,
            HttpSecurityRecorder recorder, BeanContainerBuildItem beanContainerBuildItem,
            ShutdownContextBuildItem shutdown) {
        if (authenticationHandler.isPresent()) {
            RuntimeValue<CORSConfig> programmaticCorsConfig = recorder.prepareHttpSecurityConfiguration(shutdown);
            recorder.initializeHttpAuthenticatorHandler(authenticationHandler.get().handler, beanContainerBuildItem.getValue());
            return new HttpSecurityConfigSetupCompleteBuildItem(programmaticCorsConfig);
        }

View on GitHub (pinned to e1c734241f)

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

Example fix

// before (pom.xml)
<dependency>io.quarkus:quarkus-vertx-http</dependency>

// after
<dependency>io.quarkus:quarkus-vertx-http</dependency>
<dependency>io.quarkus:quarkus-security</dependency>

Defensive patterns

Strategy: fallback

Validate before calling

boolean hasSecurity = Class.forName("io.quarkus.security.identity.SecurityIdentity", false,
    Thread.currentThread().getContextClassLoader()) != null;
if (!hasSecurity && csrfEnabled) {
    throw new IllegalStateException("CSRF requires the quarkus-security extension");
}

Try / catch

try {
    csrfBuilder.build();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("quarkus-security")) {
        throw new IllegalStateException("Add io.quarkus:quarkus-security to your pom.xml", e);
    }
    throw e;
}

Prevention

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

When it happens

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

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

Related errors

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