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.

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:
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]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.
- The class has no bean-defining annotation.
- The class is in a dependency jar that Quarkus never indexed.
- The bean exists, but ArC removed it as unused.
- 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
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:
@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:
@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:
quarkus.index-dependency.payments.group-id=dev.javahacks
quarkus.index-dependency.payments.artifact-id=payments-libThe 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:
@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:
@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 mean | Use |
|---|---|
| One of them is the normal choice at this injection point | A 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:
@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.


