Configure the DI plugin

You can configure the dependency injection (DI) plugin in your application configuration file. These settings affect the behavior of dependency resolution globally and apply to all registered dependencies.

Dependency key mapping

The ktor.di.keyMapping property defines how dependency keys are generalized and matched during resolution. This determines which registered dependencies are considered compatible when resolving a requested type.

ktor:
  di:
    keyMapping: Supertypes * Nullables * OutTypeArgumentsSupertypes * RawTypes

The above example matches the default key mapping used by the DI plugin.

Available key mapping options

Default: Uses the default combination:
Supertypes * Nullables * OutTypeArgumentsSupertypes * RawTypes
Supertypes: Allows resolving a dependency using any of its supertypes.
Nullables: Allows matching nullable and non-nullable variants of a type.
OutTypeArgumentsSupertypes: Allows covariance on out type parameters.
RawTypes: Allows resolving generic types without considering type arguments.
Unnamed: Ignores dependency names (@Named) when matching.

Combine key mapping options

You can combine key mapping options using set operators * (intersection), + (union) and () (grouping).

In the following example, a dependency registered as List<String> can be resolved as Collection<String> (Supertypes), List or List? (RawTypes and Nullables):

ktor:
  di:
    keyMapping: Supertypes + (Nullables * RawTypes)

It will not resolve as Collection?, because that combination is not included in the expression.

Conflict resolution policy

The ktor.di.conflictPolicy property controls how the DI container behaves when multiple providers are registered for the same dependency key:

ktor:
  di:
    conflictPolicy: Default

Available policies

Default: Throws an exception when a conflicting dependency is declared.
OverridePrevious: Overrides the previous dependency with the newly provided one.
IgnoreConflicts: In test environments, the DI plugin uses IgnoreConflicts by default. This allows test code to override production dependencies without triggering errors.

27 February 2026