How do you resolve the conflict of providing two different instances of the same type using qualifiers in Hilt?

Short answer

By defining custom annotations marked with @Qualifier to distinguish each instance (such as an authenticated network client and a public network client).

Explanation

When the app needs two instances of OkHttpClient or Retrofit with different configurations, Dagger fails at compile time because it cannot tell them apart. By resolving this conflict through @Qualifier, we tie each instance to a unique annotation, then use the same annotation at the injection point so Hilt knows which specific instance to supply.

Code example

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class AuthInterceptorOkHttpClient

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class PublicOkHttpClient

// At the provisioning point:
@Provides
@AuthInterceptorOkHttpClient
fun provideAuthClient(): OkHttpClient = ...

// At the point of use:
class UserRemoteDataSource @Inject constructor(
    @AuthInterceptorOkHttpClient private val client: OkHttpClient
)

Common mistakes

• Using @Named with hand-typed strings instead of writing strong custom qualifiers, which causes typos that are hard to detect at runtime.

Follow-up questions

• What is the difference between @Provides and @Binds inside Module classes in Hilt?

Sources

• Android Developers — Qualifiers in Hilt