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.
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)
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
- KnownCompatibleBeanArchiveBuildItem.Builder needs to declare
- 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/10b4545a33586c1c.
Report an issue: GitHub.