Quarkus CDI ArC Dependency Injection Explained in Depth
Learn how Quarkus ArC implements CDI: scopes, injection, producers, qualifiers, events and interceptors, and the build time rules that differ from full CDI.

Quarkus 3 does dependency injection with ArC, a CDI Lite implementation that does its work while the application is being built. If you know Spring, most concepts carry over by renaming: a scope is a lifecycle, a producer is a @Bean method, an observer is an event listener. What changes is when mistakes appear and what the runtime is allowed to do. This guide goes through each feature with a small example and then covers the rules that make ArC different from the CDI of an application server.
Beans and scopes
@ApplicationScoped
public class PriceService {
public BigDecimal priceOf(String sku) { return BigDecimal.TEN; }
}
@Path("/prices")
public class PriceResource {
private final PriceService prices;
public PriceResource(PriceService prices) {
this.prices = prices;
}
@GET
@Path("/{sku}")
public BigDecimal get(@PathParam("sku") String sku) {
return prices.priceOf(sku);
}
}A class with a single constructor needs no @Inject in Quarkus. Field injection also works, and the Quarkus guidance is to leave the field package-private (@Inject PriceService prices;) rather than private, because a private injected field forces reflection, which costs in native images. Constructor injection avoids the question and makes the dependencies visible and testable.
| Scope | Lifetime | Client proxy |
|---|---|---|
@ApplicationScoped | One for the application, created on first use | Yes |
@Singleton | One, created on first injection | No |
@RequestScoped | One per HTTP request | Yes |
@Dependent | A new instance for each injection point | No |
The practical difference between @ApplicationScoped and @Singleton is the proxy. An application-scoped bean is injected as a thin subclass that looks up the real instance on each call. That makes it lazy, replaceable in tests and safe against circular references, and costs one extra method call. A singleton is injected directly, which is slightly faster and cannot be mocked through the container's mocking support. For most services the default choice is @ApplicationScoped; use @Singleton for hot, stateless helpers. A proxied bean also may not be final and needs a no-argument constructor, though ArC generates one for you when it can.
Producers
@ApplicationScoped
class Clients {
@Produces
@ApplicationScoped
HttpClient httpClient() {
return HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(2)).build();
}
}A producer method is the equivalent of Spring's @Bean. Use one for a class you cannot annotate, such as a JDK or third-party type, and for objects that need construction logic. A matching @Disposes method receives the object when its scope ends, which is the place to close a client that holds sockets.
Qualifiers choose between implementations
@Qualifier
@Retention(RUNTIME)
@interface Fast { }
@ApplicationScoped
@Fast
class CachedPrices implements PriceSource { }
@Inject
@Fast
PriceSource source;When two beans share a type and the injection point names no qualifier, the build fails with an ambiguous dependency error, and when none matches it fails with an unsatisfied one. Both are build errors in Quarkus rather than start-up errors, which is a gain. Their causes are covered in unsatisfied and ambiguous dependencies. To pick one implementation at run time from several, inject Instance<PriceSource> and select from it. Beans reached only that way look unused to the build, so they need @Unremovable, explained below.
Events decouple components
@Inject
Event<OrderPlaced> events;
void place() {
events.fire(new OrderPlaced(42));
}
void onPlaced(@Observes OrderPlaced event) {
// runs synchronously in the caller's thread
}fire delivers to observers synchronously, in the calling thread and inside its transaction. fireAsync with @ObservesAsync delivers on another thread and outside the caller's transaction. That distinction is the cause of most surprises: an asynchronous observer that reads the order the sender has just saved may run before the commit and see nothing. The model matches Spring's ApplicationEventPublisher, minus @TransactionalEventListener.
Interceptors
@InterceptorBinding
@Retention(RUNTIME)
@interface Timed { }
@Timed
@Interceptor
@Priority(Interceptor.Priority.APPLICATION)
class TimingInterceptor {
@AroundInvoke
Object time(InvocationContext ctx) throws Exception {
long start = System.nanoTime();
try {
return ctx.proceed();
} finally {
System.out.println(ctx.getMethod() + " took " + (System.nanoTime() - start));
}
}
}Annotate a bean or a method with @Timed and the interceptor wraps the call. ArC weaves interceptors into generated subclasses at build time, so no proxy library runs at start-up. One limit follows from that: a call from one method to another inside the same bean does not pass through the interceptor, because it never leaves the instance.
What ArC does at build time
During the build, ArC resolves every injection point to exactly one bean, fails if there are none or several, and removes beans that nothing injects. That removal explains a common surprise. A bean looked up only through Instance<T>, CDI.current() or reflection is removed and then missing at run time unless it is marked @Unremovable. The reasoning behind build-time work is in build-time processing. To see the result, open the ArC page of the Dev UI in dev mode; it lists every bean, its scope and why a bean was removed.
Lifecycle callbacks and start-up work
@PostConstruct and @PreDestroy work as expected, but a lazy @ApplicationScoped bean runs @PostConstruct on its first call, not at boot. If a bean must initialise at start-up, for example to warm a cache or validate configuration, observe the start-up event.
void onStart(@Observes StartupEvent event) {
cache.warm();
}The StartupEvent fires once the container is ready and before the first request. Its counterpart ShutdownEvent is the place to flush buffers. Putting slow work in an observer keeps it visible in the start-up log, while hiding it in a lazy @PostConstruct moves the delay to a user's first request.
Configuration injection
Typed configuration follows the same injection rules. @ConfigProperty(name = "price.currency", defaultValue = "EUR") String currency; injects a single value, and @ConfigMapping interfaces group related keys. Both are validated at start-up, so a missing required key stops the application early with the key's name, which beats a null found in production. Prefer a mapping interface over many scattered fields once a bean needs more than two keys.
Choosing between the two annotations in practice
If a team cannot agree, adopt one rule: services are @ApplicationScoped, and anything that holds no state and is called in a tight loop is @Singleton. Mixed use is fine as long as nobody mocks the singletons.
Testing beans
@QuarkusTest boots the container, and @InjectMock replaces an application-scoped bean for one test.
@QuarkusTest
class PriceResourceTest {
@InjectMock
PriceService prices;
@Test
void returnsTheServicePrice() {
Mockito.when(prices.priceOf("A1")).thenReturn(BigDecimal.valueOf(5));
given().when().get("/prices/A1").then().statusCode(200).body(is("5"));
}
}This works because the application-scoped proxy can delegate to a mock. A @Singleton cannot be replaced this way, which is the practical cost of skipping the proxy.
Common ArC errors and what they mean
The build errors have a pattern. An unsatisfied dependency names the injection point and the type, so check that the bean has a scope annotation. An ambiguous dependency lists the candidates, so add a qualifier or remove one. A removed bean at run time means nothing injected it at build time, so mark it unremovable. Reading the first line of the error and the bean list it prints solves most cases without a debugger.
Where ArC differs from full CDI
ArC implements CDI Lite plus a few extras. Portable extensions, conversation scope and some decorator features are missing, and a library that depends on any of them needs a Quarkus extension instead. The comparison with the Jakarta platform is in Jakarta CDI explained. Reference material: the Quarkus CDI reference and the shorter CDI introduction.


