{"record":{"id":"e81360bad300f640","repo":"quarkusio/quarkus","slug":"knowncompatiblebeanarchivebuilditem-builder-needs","errorCode":null,"errorMessage":"KnownCompatibleBeanArchiveBuildItem.Builder needs to declare at least one compatibility reason. Artifact with following coordinates had no reason associated: <groupId>:<artifactId>","messagePattern":"KnownCompatibleBeanArchiveBuildItem\\.Builder needs to declare at least one compatibility reason\\. Artifact with following coordinates had no reason associated: <groupId>:<artifactId>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/KnownCompatibleBeanArchiveBuildItem.java","lineNumber":52,"sourceCode":"    }\n\n    /**\n     * Deprecated, use {@link KnownCompatibleBeanArchiveBuildItem#builder(String, String)} method instead.\n     * For compatibility reasons, this method automatically registers the artifact with {@link Reason#BEANS_XML_ALL}.\n     */\n    @Deprecated\n    public KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId, String classifier) {\n        this(groupId, artifactId, classifier, ArtifactCoords.TYPE_JAR, Set.of(Reason.BEANS_XML_ALL));\n    }\n\n    private KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId, String classifier, String type,\n            Set<Reason> reasons) {\n        Objects.requireNonNull(groupId, \"groupId must be set\");\n        Objects.requireNonNull(artifactId, \"artifactId must be set\");\n        Objects.requireNonNull(classifier, \"classifier must be set\");\n        Objects.requireNonNull(type, \"type must be set\");\n        if (reasons.isEmpty()) {\n            throw new IllegalStateException(\n                    \"KnownCompatibleBeanArchiveBuildItem.Builder needs to declare at least one compatibility reason. Artifact with following coordinates had no reason associated: \"\n                            + groupId + \":\" + artifactId);\n        }\n        this.groupId = groupId;\n        this.artifactId = artifactId;\n        this.classifier = classifier;\n        this.type = type;\n        this.reasons = reasons;\n    }\n\n    public static Builder builder(String groupId, String artifactId) {\n        return new Builder(groupId, artifactId);\n    }\n\n    /**\n     * An enum listing known reasons for which an archive might be marked as compatible despite using some unsupported\n     * feature such as {@code beans.xml} discovery mode {@code all} or using {@link jakarta.enterprise.inject.Specializes}\n     * annotation on its classes.","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/KnownCompatibleBeanArchiveBuildItem.java#L34-L70","documentation":"KnownCompatibleBeanArchiveBuildItem identifies a Maven artifact as a CDI Full-compatible archive, and the constructor requires a non-empty set of Reason values documenting why it is compatible. A builder without any reason() fails fast with IllegalStateException, naming the groupId:artifactId.","triggerScenarios":"Calling KnownCompatibleBeanArchiveBuildItem.builder().setGroupId(...).setArtifactId(...).setClassifier(...).setType(...).build() without adding any Reason.","commonSituations":"Extension authors whitelisting a third-party archive for full CDI support but forgetting to justify it; code refactors dropping the reasons set.","solutions":["Add at least one reason via .reason(Reason...) on the builder","Remove the build item if the archive does not need the compatibility waiver"],"exampleFix":"// before\nKnownCompatibleBeanArchiveBuildItem.builder().setGroupId(\"com.acme\").setArtifactId(\"acme-cdi\").setClassifier(\"\").setType(\"jar\").build();\n// after\nKnownCompatibleBeanArchiveBuildItem.builder().setGroupId(\"com.acme\").setArtifactId(\"acme-cdi\").setClassifier(\"\").setType(\"jar\").reason(Reason.KNOWN_JANDIDES_LIBRARY).build();","handlingStrategy":"validation","validationCode":"KnownCompatibleBeanArchiveBuildItem.Builder b = KnownCompatibleBeanArchiveBuildItem.builder()\n    .setGroupId(\"com.acme\").setArtifactId(\"acme-cdi\").setClassifier(\"\").setType(\"jar\");\nif (!hasReasons(b)) b.reason(Reason.KNOWN_COMPATIBLE_LIBRARY); // must add before build()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always add a Reason in the same builder chain","Document why each archive is whitelisted","Code-review all KnownCompatibleBeanArchive producers"],"tags":["quarkus","arc","builder","build-time"],"backgroundTag":"builder-misuse-missing-required-field","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}