{"record":{"id":"b3ea0b7745da5713","repo":"quarkusio/quarkus","slug":"principal-is-null-but-anonymous-status-is-false","errorCode":null,"errorMessage":"Principal is null but anonymous status is false","messagePattern":"Principal is null but anonymous status is false","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/security/runtime/src/main/java/io/quarkus/security/runtime/QuarkusSecurityIdentity.java","lineNumber":312,"sourceCode":"        }\n\n        /**\n         * Sets an anonymous identity status.\n         *\n         * @param anonymous the anonymous status\n         * @return This builder\n         */\n        public Builder setAnonymous(boolean anonymous) {\n            if (built) {\n                throw new IllegalStateException();\n            }\n            this.anonymous = anonymous;\n            return this;\n        }\n\n        public QuarkusSecurityIdentity build() {\n            if (principal == null && !anonymous) {\n                throw new IllegalStateException(\"Principal is null but anonymous status is false\");\n            }\n            addPossesedPermissionsChecker();\n\n            built = true;\n            return new QuarkusSecurityIdentity(this);\n        }\n\n        private void addPossesedPermissionsChecker() {\n            if (!permissions.isEmpty()) {\n                addPermissionChecker(\n                        new Function<Permission, Uni<Boolean>>() {\n\n                            @Override\n                            public Uni<Boolean> apply(Permission requiredPermission) {\n\n                                for (Permission possessedPermission : permissions) {\n                                    if (possessedPermission.implies(requiredPermission)) {\n                                        return Uni.createFrom().item(true);","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/security/runtime/src/main/java/io/quarkus/security/runtime/QuarkusSecurityIdentity.java#L294-L330","documentation":"QuarkusSecurityIdentity.Builder.build() validates that an identity is coherent: every identity must either have a non-null Principal or be explicitly marked anonymous. If principal==null and anonymous==false the identity would represent an authenticated user with no name, so the builder refuses to construct it. This is a programming/configuration bug in whatever code assembled the identity.","triggerScenarios":"Calling QuarkusSecurityIdentity.builder().build() (directly or via a custom IdentityProvider / SecurityIdentityAugmentor) without calling setPrincipal(...) and without calling setAnonymous(true).","commonSituations":"A custom IdentityProvider that authenticates tokens but forgets to set a Principal; an augmentor that adds roles to an identity but rebuilds it without copying the principal; tests constructing identities by hand.","solutions":["Set a Principal on the builder: builder.setPrincipal(new QuarkusPrincipal(username)) before build().","If the identity genuinely has no user, call builder.setAnonymous(true) before build().","When rebuilding an existing identity in an augmentor, copy the principal: builder.setPrincipal(identity.getPrincipal()).","Audit custom IdentityProvider/Augmentor code paths that construct identities for the missing branch.","Add a test that builds the identity your provider produces so build() validation runs in CI."],"exampleFix":"// before\nQuarkusSecurityIdentity identity = QuarkusSecurityIdentity.builder()\n        .addRole(\"user\")\n        .build(); // IllegalStateException\n// after\nQuarkusSecurityIdentity identity = QuarkusSecurityIdentity.builder()\n        .setPrincipal(new QuarkusPrincipal(tokenSubject))\n        .addRole(\"user\")\n        .build();","handlingStrategy":"validation","validationCode":"var builder = QuarkusSecurityIdentity.builder();\nif (principal == null && !anonymousFlag) {\n    throw new IllegalStateException(\"Identity must set a Principal or be anonymous\");\n}","typeGuard":"boolean isValidIdentity(QuarkusSecurityIdentity.Builder b, Principal p, boolean anonymous) {\n    return p != null || anonymous;\n}","tryCatchPattern":null,"preventionTips":["Always call setPrincipal() for authenticated identities","Call setAnonymous(true) for unauthenticated identities","In augmentors, copy identity.getPrincipal() into the new builder","Unit-test identity construction for every custom provider"],"tags":["security","identity","builder-validation"],"backgroundTag":"identity-missing-principal","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"}