ADR-0006: Disambiguate Spring beans by concrete type, not field @Qualifier
Status: Accepted
Date: 2026-05-31
Scope: core (any Spring backend using Lombok constructors)
Context
When several beans are assignable to the same interface (e.g. @EnableAsync +
scheduling expose two TaskExecutor-assignable beans), an injected dependency
needs disambiguation. The reflex is a field-level @Qualifier on a @RequiredArgsConstructor class — but Lombok generates the constructor, and a
field @Qualifier is only carried onto the generated constructor parameter if a lombok.config declares it under lombok.copyableAnnotations. These backends
keep no lombok.config (and in Expenses the Docker build copies only mvnw/pom.xml/.mvn/src anyway), so a field @Qualifier on a Lombok
constructor is silently not honored → Spring sees an ambiguous bean and fails
to start.
Decision
Disambiguate by injecting the concrete type, not a field @Qualifier, on @RequiredArgsConstructor classes. Inject the bean’s concrete class (which is
unambiguous by type) rather than the shared interface + a qualifier.
Example (Expenses: presentation/chat/webservice/ChatWebService.java): inject the
concrete ThreadPoolTaskExecutor applicationTaskExecutor, not @Qualifier("applicationTaskExecutor") TaskExecutor — only the former survives
Lombok’s generated constructor here.
If a future need genuinely requires field-level qualifiers on Lombok constructors,
that requires adding a lombok.config with copyableAnnotationsand ensuring
it’s copied into the Docker image — neither of which is true today, so don’t rely
on it.
Consequences
Bean wiring is unambiguous without depending on a lombok.config we don’t
maintain; avoids an ambiguous-bean startup failure.
Slightly less flexible than qualifiers, but type-based injection is clearer anyway.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
@Service@RequiredArgsConstructorpublic class ChatWebService { // Concrete type — unambiguous by type alone. private final ThreadPoolTaskExecutor applicationTaskExecutor; // NOT this: Lombok's generated constructor does not copy the annotation, // so the qualifier is lost and startup fails on an ambiguous TaskExecutor. // // @Qualifier("applicationTaskExecutor") // private final TaskExecutor applicationTaskExecutor;}
Lombok generates the constructor, and field annotations are not copied onto the
generated constructor parameter unless lombok.config declares copyableAnnotations.
There is no such file in this repo, and if one were added it would also have to be copied
into the Docker image — so the qualifier silently does nothing and Spring fails to start
on an ambiguous bean.
Injecting the concrete class sidesteps the whole problem: ThreadPoolTaskExecutor matches
exactly one bean, so no disambiguation is needed at all.