quarkusio/quarkus · error · IllegalStateException

KnownCompatibleBeanArchiveBuildItem.Builder needs to…

Error message

KnownCompatibleBeanArchiveBuildItem.Builder needs to declare at least one compatibility reason. Artifact with following coordinates had no reason associated: <groupId>:<artifactId>

What it means

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.

Solutions

1. Add at least one reason via .reason(Reason...) on the builder
2. Remove the build item if the archive does not need the compatibility waiver

Example fix

// before
KnownCompatibleBeanArchiveBuildItem.builder().setGroupId("com.acme").setArtifactId("acme-cdi").setClassifier("").setType("jar").build();
// after
KnownCompatibleBeanArchiveBuildItem.builder().setGroupId("com.acme").setArtifactId("acme-cdi").setClassifier("").setType("jar").reason(Reason.KNOWN_JANDIDES_LIBRARY).build();

KnownCompatibleBeanArchiveBuildItem.Builder b = KnownCompatibleBeanArchiveBuildItem.builder()
    .setGroupId("com.acme").setArtifactId("acme-cdi").setClassifier("").setType("jar");
if (!hasReasons(b)) b.reason(Reason.KNOWN_COMPATIBLE_LIBRARY); // must add before build()

When it happens

Trigger: Calling KnownCompatibleBeanArchiveBuildItem.builder().setGroupId(...).setArtifactId(...).setClassifier(...).setType(...).build() without adding any Reason.

Common situations: Extension authors whitelisting a third-party archive for full CDI support but forgetting to justify it; code refactors dropping the reasons set.

Related errors

• A matching predicate must be set!
• AnnotationTransformation is not an AnnotationsTransformer
• Different default scopes defined for additional bean class
• Invalid configuration value set for…
• Invalid regex pattern

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

Appendix: source

Thrown at extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/KnownCompatibleBeanArchiveBuildItem.java:52

    }

    /**
     * Deprecated, use {@link KnownCompatibleBeanArchiveBuildItem#builder(String, String)} method instead.
     * For compatibility reasons, this method automatically registers the artifact with {@link Reason#BEANS_XML_ALL}.
     */
    @Deprecated
    public KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId, String classifier) {
        this(groupId, artifactId, classifier, ArtifactCoords.TYPE_JAR, Set.of(Reason.BEANS_XML_ALL));
    }

    private KnownCompatibleBeanArchiveBuildItem(String groupId, String artifactId, String classifier, String type,
            Set<Reason> reasons) {
        Objects.requireNonNull(groupId, "groupId must be set");
        Objects.requireNonNull(artifactId, "artifactId must be set");
        Objects.requireNonNull(classifier, "classifier must be set");
        Objects.requireNonNull(type, "type must be set");
        if (reasons.isEmpty()) {
            throw new IllegalStateException(
                    "KnownCompatibleBeanArchiveBuildItem.Builder needs to declare at least one compatibility reason. Artifact with following coordinates had no reason associated: "
                            + groupId + ":" + artifactId);
        }
        this.groupId = groupId;
        this.artifactId = artifactId;
        this.classifier = classifier;
        this.type = type;
        this.reasons = reasons;
    }

    public static Builder builder(String groupId, String artifactId) {
        return new Builder(groupId, artifactId);
    }

    /**
     * An enum listing known reasons for which an archive might be marked as compatible despite using some unsupported
     * feature such as {@code beans.xml} discovery mode {@code all} or using {@link jakarta.enterprise.inject.Specializes}
     * annotation on its classes.

View on GitHub (pinned to e1c734241f)