quarkusio/quarkus · error · IllegalStateException

Please add an extension that provides a CSRF prevention feat

Error message

Please add an extension that provides a CSRF prevention feature, for example the Quarkus REST Cross-Site Request Forgery Prevention `quarkus-rest-csrf` extension

What it means

CSRF.builder() throws IllegalStateException because in vertx-http the CSRF capability is absent: the static method is bytecode-transformed at build time to return a real builder only when an extension providing CSRF prevention (e.g. quarkus-rest-csrf) is present. Hitting the throw means no CSRF-capable extension is on the classpath.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/security/CSRF.java:21

import java.time.Duration;
import java.util.Set;

import io.smallrye.common.annotation.Experimental;

/**
 * This class provides a way to configure the Cross-Site Request Forgery (CSRF) prevention.
 */
@Experimental("This API is currently experimental and might get changed")
public interface CSRF {

    /**
     * Creates the CSRF prevention configuration builder.
     *
     * @return new {@link CSRF.Builder} instance
     */
    static Builder builder() {
        // when the CSRF capability is present, this method is transformed during the build time and returns a builder
        throw new IllegalStateException("Please add an extension that provides a CSRF prevention feature, for example "
                + "the Quarkus REST Cross-Site Request Forgery Prevention `quarkus-rest-csrf` extension");
    }

    /**
     * The Quarkus CSRF prevention configuration builder.
     */
    interface Builder {

        /**
         * Form field name which keeps a CSRF token. The default field name is "csrf-token".
         *
         * @param formFieldName form field name
         * @return this builder
         */
        Builder formFieldName(String formFieldName);

        /**
         * The token header name which can provide a CSRF token. The default name is "X-CSRF-TOKEN".

View on GitHub (pinned to e1c734241f)

Solutions

Add the quarkus-rest-csrf dependency (io.quarkus:quarkus-rest-csrf) to the project
Rebuild/reload so the build-time transformation applies
If CSRF is not needed, remove the CSRF.builder() call

Example fix

// before (pom.xml) — only quarkus-vertx-http present
csrfBuilder = CSRF.builder();
// after
// add dependency: io.quarkus:quarkus-rest-csrf
csrfBuilder = CSRF.builder();

Defensive patterns

Strategy: try-catch

Validate before calling

// pom.xml guard
// ensure dependency exists:
// <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-rest-csrf</artifactId></dependency>

Try / catch

try {
    builder = CSRF.builder();
} catch (IllegalStateException e) {
    // CSRF extension missing — handle absence or fail fast with a clear message
    throw new IllegalStateException("Add io.quarkus:quarkus-rest-csrf to use CSRF", e);
}

Prevention

Add quarkus-rest-csrf dependency whenever CSRF.builder() is used
Keep CSRF usage and the extension dependency in the same module
Run a build/test early to catch missing capability at startup

When it happens

Trigger: Calling CSRF.builder() in an application that lacks quarkus-rest-csrf (or any other CSRF-providing extension).

Common situations: App depends only on quarkus-vertx-http / quarkus-rest without the CSRF extension; dependency removed during a cleanup; wrong artifact (RESTEasy Classic vs REST) mismatch.

Related errors

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