{"record":{"id":"cb1365b1e0da2f47","repo":"quarkusio/quarkus","slug":"cannot-configure-basic-authentication-programmatic","errorCode":null,"errorMessage":"Cannot configure basic authentication programmatically because the authentication realm has already been configured in the 'application.properties' file","messagePattern":"Cannot configure basic authentication programmatically because the authentication realm has already been configured in the 'application\\.properties' file","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java","lineNumber":129,"sourceCode":"        }\n        this.csrf = csrf;\n        return this;\n    }\n\n    @Override\n    public HttpSecurity mechanism(HttpAuthenticationMechanism mechanism) {\n        Objects.requireNonNull(mechanism);\n        if (mechanism.getClass() == FormAuthenticationMechanism.class) {\n            final FormAuthConfig defaults = HttpSecurityUtils.getDefaultAuthConfig().auth().form();\n            final FormAuthConfig actualConfig = vertxHttpConfig.auth().form();\n            if (!actualConfig.equals(defaults)) {\n                throw new IllegalArgumentException(\"Cannot configure form-based authentication programmatically \"\n                        + \"because it has already been configured in the 'application.properties' file\");\n            }\n        } else if (mechanism.getClass() == BasicAuthenticationMechanism.class) {\n            String actualRealm = vertxHttpConfig.auth().realm().orElse(null);\n            if (actualRealm != null) {\n                throw new IllegalArgumentException(\"Cannot configure basic authentication programmatically because \"\n                        + \"the authentication realm has already been configured in the 'application.properties' file\");\n            }\n        } else if (mechanism.getClass() == MtlsAuthenticationMechanism.class) {\n            boolean mTlsEnabled = !ClientAuth.NONE.equals(clientAuth);\n            if (mTlsEnabled) {\n                // current we do not allow \"merging\" (or overriding) of the configuration provided in application.properties\n                // there shouldn't be a technical issue allowing that, but that's the behavior we have for other mechanisms\n                // as well, so this method only allows to \"enable\" mTLS, never disable or change configuration provided\n                // properties file\n                throw new IllegalArgumentException(\"TLS client authentication has already been enabled with this API or\"\n                        + \" with the 'quarkus.http.ssl.client-auth' configuration property\");\n            }\n            var mTLS = ((MtlsAuthenticationMechanism) mechanism);\n            clientAuth = mTLS.getTlsClientAuth();\n            if (mTLS.getHttpServerTlsConfigName().isPresent()) {\n                if (httpServerTlsConfigName.isPresent()) {\n                    throw new IllegalArgumentException(\"Cannot configure TLS configuration name programmatically because it \"\n                            + \" has already been configured with the 'quarkus.http.tls-configuration-name' configuration property\");","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java#L111-L147","documentation":"BasicAuthenticationMechanism registered programmatically conflicts with a realm already set via the quarkus.http.auth.realm (or related auth realm) property. Quarkus refuses to merge: when the realm is present in application.properties, programmatic basic auth configuration throws an IllegalArgumentException. This guarantees the realm identity is unambiguous.","triggerScenarios":"Calling httpSecurity.basic(\"my-realm\") or httpSecurity.mechanism(new BasicAuthenticationMechanism(...)) while application.properties defines quarkus.http.auth.realm (or basic auth realm properties).","commonSituations":"Apps migrated from properties-based security to programmatic HttpSecurity while leaving quarkus.http.auth.realm in the properties file; inherited application.properties files where the realm was set long ago and forgotten.","solutions":["Remove quarkus.http.auth.realm (and basic auth realm properties) from application.properties before registering basic auth in code.","Keep basic auth entirely in application.properties and remove the programmatic basic()/mechanism() call.","Align on one configuration source and delete the other."],"exampleFix":"// before (application.properties)\nquarkus.http.auth.realm=secure-realm\n// code: httpSecurity.basic(\"secure-realm\") // throws\n// after: delete the realm property (or drop the programmatic call)\nhttpSecurity.basic(\"secure-realm\");","handlingStrategy":"validation","validationCode":"// ensure no realm is set in properties before programmatic basic auth\n// ConfigProvider.getConfig().getOptionalValue(\"quarkus.http.auth.realm\", String.class)\n//     .ifPresent(r -> { throw new IllegalStateException(\"Realm already set in application.properties\"); });\nhttpSecurity.basic(\"my-realm\");","typeGuard":null,"tryCatchPattern":"try {\n    httpSecurity.basic(realm);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"basic authentication\")) {\n        log.warn(\"Realm already configured in application.properties; keeping properties-based config\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Remove quarkus.http.auth.realm from application.properties when switching to programmatic basic auth.","Document in the team runbook whether basic auth lives in properties or code.","Check generated/included properties files (e.g. application.properties includes) for realm entries."],"tags":["quarkus","http-security","basic-auth","duplicate-configuration"],"backgroundTag":"duplicate-configuration-source","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"}