{"record":{"id":"560dc1a30b24d1b8","repo":"quarkusio/quarkus","slug":"please-add-an-extension-that-provides-a-csrf-preve","errorCode":null,"errorMessage":"Please add an extension that provides a CSRF prevention feature, for example the Quarkus REST Cross-Site Request Forgery Prevention `quarkus-rest-csrf` extension","messagePattern":"Please add an extension that provides a CSRF prevention feature, for example the Quarkus REST Cross-Site Request Forgery Prevention `quarkus-rest-csrf` extension","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/security/CSRF.java","lineNumber":21,"sourceCode":"import java.time.Duration;\nimport java.util.Set;\n\nimport io.smallrye.common.annotation.Experimental;\n\n/**\n * This class provides a way to configure the Cross-Site Request Forgery (CSRF) prevention.\n */\n@Experimental(\"This API is currently experimental and might get changed\")\npublic interface CSRF {\n\n    /**\n     * Creates the CSRF prevention configuration builder.\n     *\n     * @return new {@link CSRF.Builder} instance\n     */\n    static Builder builder() {\n        // when the CSRF capability is present, this method is transformed during the build time and returns a builder\n        throw new IllegalStateException(\"Please add an extension that provides a CSRF prevention feature, for example \"\n                + \"the Quarkus REST Cross-Site Request Forgery Prevention `quarkus-rest-csrf` extension\");\n    }\n\n    /**\n     * The Quarkus CSRF prevention configuration builder.\n     */\n    interface Builder {\n\n        /**\n         * Form field name which keeps a CSRF token. The default field name is \"csrf-token\".\n         *\n         * @param formFieldName form field name\n         * @return this builder\n         */\n        Builder formFieldName(String formFieldName);\n\n        /**\n         * The token header name which can provide a CSRF token. The default name is \"X-CSRF-TOKEN\".","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/security/CSRF.java#L3-L39","documentation":"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.","triggerScenarios":"Calling CSRF.builder() in an application that lacks quarkus-rest-csrf (or any other CSRF-providing extension).","commonSituations":"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.","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"],"exampleFix":"// before (pom.xml) — only quarkus-vertx-http present\ncsrfBuilder = CSRF.builder();\n// after\n// add dependency: io.quarkus:quarkus-rest-csrf\ncsrfBuilder = CSRF.builder();","handlingStrategy":"try-catch","validationCode":"// pom.xml guard\n// ensure dependency exists:\n// <dependency><groupId>io.quarkus</groupId><artifactId>quarkus-rest-csrf</artifactId></dependency>","typeGuard":null,"tryCatchPattern":"try {\n    builder = CSRF.builder();\n} catch (IllegalStateException e) {\n    // CSRF extension missing — handle absence or fail fast with a clear message\n    throw new IllegalStateException(\"Add io.quarkus:quarkus-rest-csrf to use CSRF\", e);\n}","preventionTips":["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"],"tags":["quarkus","missing-extension","csrf","illegal-state","classpath"],"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"}