quarkusio/quarkus · error · IllegalStateException

KnownCompatibleBeanArchiveBuildItem.Builder needs to declare

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.

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)

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: <
• Invalid configuration value set for 'quarkus.arc.remove-unus
• Different default scopes defined for additional bean class:
• Unexpected value: <arcConfig.optimizeContexts()>

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