quarkusio/quarkus · error · IllegalArgumentException

CSRF must not be null

Error message

CSRF must not be null

What it means

HttpSecurity.csrf(CSRF) stores the programmatic CSRF configuration on the HttpSecurity builder. The Quarkus HTTP security API rejects null arguments eagerly so that a misconfigured builder fails fast instead of silently skipping CSRF protection. Throwing here prevents a null CSRF object from flowing into security runtime setup where the failure would be much harder to diagnose.

Source

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

            // for example SmallRye OpenAPI extension adds a management URL to 'origins'
            // and we want users know that they are loosing some configuration
            final List<String> newOrigins = newCorsConfig.origins().orElse(List.of());
            final String missingOrigins = corsConfig.origins().get().stream()
                    .filter(origin -> !newOrigins.contains(origin)).collect(Collectors.joining(","));
            if (!missingOrigins.isEmpty()) {
                LOG.warnf(
                        "CORS are configured programmatically, but previously configured '%s' origins are missing in the new configuration",
                        missingOrigins);
            }
        }
        corsConfig = newCorsConfig;
        return this;
    }

    @Override
    public HttpSecurity csrf(CSRF csrf) {
        if (csrf == null) {
            throw new IllegalArgumentException("CSRF must not be null");
        }
        this.csrf = csrf;
        return this;
    }

    @Override
    public HttpSecurity mechanism(HttpAuthenticationMechanism mechanism) {
        Objects.requireNonNull(mechanism);
        if (mechanism.getClass() == FormAuthenticationMechanism.class) {
            final FormAuthConfig defaults = HttpSecurityUtils.getDefaultAuthConfig().auth().form();
            final FormAuthConfig actualConfig = vertxHttpConfig.auth().form();
            if (!actualConfig.equals(defaults)) {
                throw new IllegalArgumentException("Cannot configure form-based authentication programmatically "
                        + "because it has already been configured in the 'application.properties' file");
            }
        } else if (mechanism.getClass() == BasicAuthenticationMechanism.class) {
            String actualRealm = vertxHttpConfig.auth().realm().orElse(null);
            if (actualRealm != null) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a non-null CSRF instance, e.g. httpSecurity.csrf(CSRF.defaultInstance()) or a properly built CSRF object.
2. Guard the call: only invoke csrf(...) when the CSRF object is non-null, and otherwise rely on configuration-file CSRF settings.
3. Check the producer of the CSRF value (factory/supplier/config) for a code path returning null and fix it.

Example fix

// before
CSRF csrf = loadCsrfConfig(); // may return null
httpSecurity.csrf(csrf);
// after
CSRF csrf = loadCsrfConfig();
if (csrf != null) {
    httpSecurity.csrf(csrf);
}

if (csrf == null) {
    throw new IllegalStateException("CSRF config must be built before HttpSecurity.csrf() is called");
}
httpSecurity.csrf(csrf);

boolean isUsableCsrf(CSRF csrf) {
    return csrf != null;
}

try {
    httpSecurity.csrf(csrf);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("CSRF must not be null")) {
        log.error("CSRF configuration missing; defaulting to config-file CSRF settings");
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling httpSecurity.csrf(null) directly, or passing a variable/field that resolves to null (e.g. a conditionally-built CSRF instance or an uninitialized supplier result) to csrf().

Common situations: Developers building security configuration dynamically in code where the CSRF config is produced by a factory that can return null on some code paths, or refactoring code where a CSRF constant was removed and the variable now defaults to null.

Related errors

• Client authentication cannot be null
• Extension passed an invalid shutdown handler
• Extension passed an invalid last shutdown handler
• Key cannot be null
• The `mails` parameter must not be `null`

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