Skip to content
javahacks.dev
Quarkus

Fix Quarkus Unsatisfied Dependency and Ambiguous Beans

Fix Quarkus build failures about unsatisfied or ambiguous CDI dependencies, including unused beans that were removed and libraries missing an index.

6 min read
Summarize in AI
Flat illustration of a Spring container wiring beans together, with the Quarkus, Spring Boot, JUnit5 and Spring logos.

The build fails, not the run. That is how Quarkus is designed, and it is also why the message looks alien to anyone arriving from Spring, where the same mistake shows up when the context starts. There are two messages, and they have opposite causes:

Text
jakarta.enterprise.inject.spi.DeploymentException: Unsatisfied dependency for type dev.javahacks.PaymentGateway and qualifiers [@Default]
	- java member: dev.javahacks.OrderService#gateway
	- declared on CLASS bean [types=[dev.javahacks.OrderService, java.lang.Object], qualifiers=[@Default, @Any], target=dev.javahacks.OrderService]
Text
jakarta.enterprise.inject.AmbiguousResolutionException: Ambiguous dependencies for type dev.javahacks.PaymentGateway and qualifiers [@Default]
	- available beans:
		- CLASS bean [... StripeGateway]
		- CLASS bean [... PaypalGateway]

Quarkus ships its own CDI container, ArC, and ArC resolves every injection point while the application is being built. A missing bean and a duplicate bean both stop mvn package or quarkus dev, with the injection point named in the first line. Read that line before changing anything: OrderService#gateway tells you which field is asking, and the type tells you what it wants. This post covers Quarkus 3 and assumes the jakarta.* packages. For the Spring versions of the same mistake, see no qualifying bean and the unique-bean exception.

Unsatisfied: find out which of four things happened

"Unsatisfied" means ArC looked for a bean of the requested type and qualifiers and found none. Four situations produce that, and they are worth checking in this order because the cheap ones come first.

  1. The class has no bean-defining annotation.
  2. The class is in a dependency jar that Quarkus never indexed.
  3. The bean exists, but ArC removed it as unused.
  4. The qualifiers at the injection point do not match the ones on the bean.

The Dev UI answers all four at once. Start quarkus dev, open http://localhost:8080/q/dev-ui, and the ArC card lists every bean with its scope, qualifiers and injection points. If the class is on the list, the problem is the qualifier or the removal. If it is not, the problem is discovery.

The class is not a bean

java
public class StripeGateway implements PaymentGateway { }

A plain class with no scope annotation is not a bean in Quarkus. Spring would pick it up through @Component scanning, but CDI needs a bean-defining annotation. Add the scope that matches the lifetime you want:

java
@ApplicationScoped
public class StripeGateway implements PaymentGateway { }

@ApplicationScoped is the usual choice for a stateless service and creates a client proxy, so the instance is created lazily on first call. @Singleton skips the proxy, which makes it marginally cheaper and also means the bean is created at injection time. @Dependent gives each injection point its own instance. Quarkus also treats a class with a single @Inject constructor or a producer as bean-defining in some cases, but relying on that makes the code harder to read than a one-line annotation.

A related trap is a producer method that lives in a class which is itself not a bean:

java
@ApplicationScoped
public class GatewayProducer {

    @Produces
    @ApplicationScoped
    PaymentGateway gateway(PaymentConfig config) {
        return new StripeGateway(config.apiKey());
    }
}

The producer class needs a scope, and the produced bean needs its own. Leave off the second one and the product is @Dependent, which is a legitimate choice, but then every injection point gets a new StripeGateway.

The bean lives in a library jar

ArC discovers beans by reading a Jandex index, which is a precomputed list of the annotated classes in a jar. Your own module gets one automatically. A dependency has one only if its authors built it in. If the class comes from a shared module in your company, its annotations are invisible until you do one of two things.

The better fix is on the library side: add the Jandex Maven plugin, or an empty META-INF/beans.xml, so every consumer benefits. When you do not own the library, index it from the application:

src/main/resources/application.propertiesproperties
quarkus.index-dependency.payments.group-id=dev.javahacks
quarkus.index-dependency.payments.artifact-id=payments-lib

The word payments is only a label that ties the two properties together. Restart dev mode after adding them, because the index is built at augmentation time.

ArC removed the bean

To keep native images and startup lean, ArC deletes any bean that nothing injects. That is a sensible default until you look a bean up dynamically:

java
@Inject
Instance<PaymentGateway> gateways;

PaymentGateway forCurrency(String currency) {
    return gateways.stream()
            .filter(g -> g.supports(currency))
            .findFirst()
            .orElseThrow();
}

No injection point asks for StripeGateway by its own type, so ArC decides it is dead code and removes it. The symptom is confusing because the bean is there in the source and absent at run time. Mark it so the optimizer leaves it alone:

java
@ApplicationScoped
@Unremovable
public class StripeGateway implements PaymentGateway { }

You can do the same for a whole package or type with quarkus.arc.unremovable-types. While diagnosing, quarkus.arc.remove-unused-beans=none turns the optimization off entirely. Do not leave it that way in a shipped service without a reason, since the removal is part of why Quarkus images are small.

The qualifier does not match

A bean annotated @Named("paypal") is not injectable at a plain @Inject PaymentGateway point if the bean also carries a custom qualifier, and the reverse is true too. Compare the qualifier list in the error ([@Default] in the examples above) with the one the Dev UI shows for the bean.

Ambiguous: pick a rule instead of deleting a bean

"Ambiguous" means two or more beans fit one injection point. Deleting one of them is rarely the answer, because both usually exist for a reason. Choose the mechanism that states your intent:

What you meanUse
One of them is the normal choice at this injection pointA qualifier at the injection point
A library supplies a fallback the application may replace@DefaultBean on the fallback
A test should swap in a fake@Alternative with @Priority(1), or @InjectMock
Every implementation is wanted@All List<PaymentGateway> or Instance<PaymentGateway>

A custom qualifier gives the most readable result when two implementations are both first-class:

java
@Qualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
public @interface Paypal { }

@ApplicationScoped
@Paypal
class PaypalGateway implements PaymentGateway { }

@ApplicationScoped
class StripeGateway implements PaymentGateway { }   // keeps @Default

@Inject
@Paypal
PaymentGateway paypal;

@Inject
PaymentGateway stripe;

The unqualified bean keeps @Default, so existing injection points keep working and only the new one opts in.

@DefaultBean solves a different problem, and it is the one extension authors hit. A library ships a default Clock or ObjectMapper customizer and wants an application bean of the same type to win without a configuration property. Mark the library's bean @DefaultBean and ArC drops it as soon as any other bean of that type exists.

For tests, @Alternative with @Priority(1) replaces a bean for the whole application, which is rarely what a single test wants. @InjectMock from quarkus-junit5-mockito replaces it for one test class and restores it afterwards, and it is the better default.

The case that looks the same and is not

A Spring habit causes a lot of these errors: conditional beans. In Spring you reach for @ConditionalOnProperty. In Quarkus the equivalents are @IfBuildProperty, @UnlessBuildProperty and @IfBuildProfile, and they are evaluated at build time. If a bean is guarded by @IfBuildProfile("prod") and you run in dev mode, the bean does not exist and you get an unsatisfied dependency for a class that is plainly annotated. The Dev UI shows the profile in the header, so check that before suspecting the annotation.

Where this does not apply

ArC implements a subset of CDI Lite plus its own additions. Portable extensions, @Decorator details and some Instance behaviours differ from what a full Jakarta EE server does, and the CDI reference lists the exact differences. If the error is a ClassNotFoundException or a failure in a native build, the cause is reflection or resource registration, not bean resolution. The reason these errors arrive at build time is explained in build-time processing, and the CDI integration guide is the shortest official introduction.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.