What causes "A matching predicate must be set!" in quarkusio/quarkus?

Add a match() call to the builder before build()

quarkusio/quarkus · error · IllegalStateException

A matching predicate must be set!

Error message

A matching predicate must be set!

What it means

AutoAddScopeBuildItem.Builder.build() requires that a matching predicate (set via match()) was configured. Without one, the build item would have no way to decide which classes to annotate, so it fails fast with IllegalStateException.

Solutions

Add a match() call to the builder before build()
Use AutoAddScopeBuildItem.builder().match(className).defaultScope(...).build() pattern
Consider annotating the class directly with the scope instead of using auto-add

Example fix

// before
AutoAddScopeBuildItem.builder().defaultScope(ApplicationScoped.class).build();
// after
AutoAddScopeBuildItem.builder().match(c -> c.declaredAnnotations().contains(DOTNAME_PATH)).defaultScope(ApplicationScoped.class).build();

Defensive patterns

Strategy: validation

Validate before calling

AutoAddScopeBuildItem.Builder b = AutoAddScopeBuildItem.builder().defaultScope(ApplicationScoped.class);
Objects.requireNonNull(b, "builder");
// ensure match() is called before build() — add an assertion in the build step
assert hasMatchPredicate : "match() must be set before build()";

Prevention

Always pair builder() with match() in the same statement chain
Use the fluent chain in a single expression so build() is last
Review builder usage with a unit test constructing each build item

When it happens

Trigger: Calling builder().defaultScope(...).build() (or similar) without ever invoking match(BiPredicate/DotName...) on the builder.

Common situations: Extension authors copying an AutoAddScopeBuildItem example and omitting the match() call; refactors that remove the predicate but leave build().

Related errors

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

Appendix: source

Thrown at extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/AutoAddScopeBuildItem.java:309

        /**
         * The final predicate is a short-circuiting logical AND of the previous predicate (if any) and this condition.
         *
         * @param other
         * @return self
         */
        public Builder and(MatchPredicate other) {
            if (matchPredicate == null) {
                matchPredicate = other;
            } else {
                matchPredicate = matchPredicate.and(other);
            }
            return this;
        }

        public AutoAddScopeBuildItem build() {
            if (matchPredicate == null) {
                throw new IllegalStateException("A matching predicate must be set!");
            }
            return new AutoAddScopeBuildItem(matchPredicate, requiresContainerServices, defaultScope, unremovable, reason,
                    priority, scopeAlreadyAdded);
        }
    }

}

View on GitHub (pinned to e1c734241f)