Skip to main content
Version: 4.2

Compiler Plugin Options

This page lists every option of the Koin Compiler Plugin, set in the koinCompiler { } block of your build.gradle.kts. It assumes the plugin is installed (see Compiler Plugin Setup). The options apply to the Compiler Plugin DSL and to annotations alike.

All options​

// build.gradle.kts
plugins {
    alias(libs.plugins.koin.compiler)
}

koinCompiler {
    compileSafety = true
    skipDefaultValues = true
    unsafeDslChecks = true
    userLogs = false
    debugLogs = false
}
OptionTypeDefaultEffect
compileSafetyBooleantrueValidates the dependency graph at build time
strictSafetyBooleanAuto-detectedRe-runs the full-graph check on every build of the aggregator module
strictSafetyForceOffBooleanfalseConfirms a wrong strictSafety auto-detection and turns it off
skipDefaultValuesBooleantrueUses Kotlin default values instead of resolving those parameters
unsafeDslChecksBooleantrueRequires create() to be the only instruction in its lambda
userLogsBooleanfalseLogs the components the plugin detects
debugLogsBooleanfalseLogs the plugin internals
logSeverityString"warning"Severity of the plugin's informational output
versionCheckSeverityString"warning"Severity of the Kotlin version compatibility warning
aiAssistBooleantrueAdds one help line at the end of a build that has Koin diagnostics

compileSafety​

When enabled, the plugin checks at build time that every dependency in the graph can be resolved: missing definitions, qualifier mismatches, circular dependencies, and get() or inject() call sites with no matching definition. A problem fails the build instead of crashing at runtime.

koinCompiler {
    compileSafety = false
}

Keep it enabled. Turning it off removes every compile-time check and makes strictSafety have no effect. What gets checked is described in Compile-Time Safety.

strictSafety​

The full-graph check runs in the module that starts Koin (the aggregator: the Gradle module that contains startKoin, koinApplication or @KoinApplication). Kotlin incremental compilation can mark that module up to date when the graph changed elsewhere, for example after an edit inside a module { } lambda body. The check would then not run again, and the error would show up at runtime.

strictSafety makes the aggregator's compileKotlin task re-run on every build, with no build cache and no up-to-date skip. Library and feature modules stay incremental.

You don't need to set it. When the option is unset, the Gradle plugin scans the module sources for startKoin, koinApplication or @KoinApplication and turns it on for that module. A lifecycle log line announces the decision:

[Koin] Auto-enabling strictSafety on :app (detected startKoin / @KoinApplication / koinApplication).

Set strictSafety = true to force it on a module the detection misses:

koinCompiler {
    strictSafety = true
}

Setting strictSafety = false has no effect on a module where an entry point is detected (since Compiler Plugin 1.1.0). It only matters on modules without a detected entry point. The option has no effect when compileSafety = false.

The cost is one full recompilation of the aggregator module per build. Background on the incremental compilation gap is in koin-compiler-plugin issue #32.

strictSafetyForceOff​

The detection is a text match. It also matches startKoin in a comment or a string literal, and then turns strictSafety on for a module that is not an aggregator. If you have checked that the match is wrong, set both options:

koinCompiler {
    strictSafety = false
    strictSafetyForceOff = true
}

Both are needed: strictSafetyForceOff only applies together with strictSafety = false. Use it only on a confirmed misfire. On a real entry point it disables the re-run, and a graph error can then reach runtime after an incremental build.

skipDefaultValues​

When enabled, a non-nullable parameter with a Kotlin default value keeps its default and is not resolved from Koin:

@Singleton
class ApiClient(
    val repository: UserRepository,                         // resolved from Koin
    val timeout: Int = 30_000,                              // Kotlin default
    @Property("api_url") val url: String = "https://...",   // resolved, it is annotated
    val logger: Logger? = null,                             // resolved with getOrNull()
)

Nullable parameters are still resolved with getOrNull(). Parameters with @Named, @Qualifier, @InjectedParam or @Property are always resolved, whatever their default value. Set skipDefaultValues = false to resolve every parameter from Koin.

unsafeDslChecks​

When enabled, a create(::T) call must be the only instruction in its definition lambda. This keeps the lambda something the plugin can analyze and validate. A violation fails the build:

[Koin][KOIN-S001] create(::UserRepository) must be the only instruction in the lambda. Other statements are not allowed when using create(). To disable this check, set koinCompiler { unsafeDslChecks = false } in your build.gradle.kts

Set it to false while you migrate Classic DSL code that runs other statements inside a create() lambda, then turn it back on.

userLogs and debugLogs​

userLogs = true prints what the plugin detects and processes: DSL definitions it intercepts (single<T>(), factory<T>()), annotated classes (@Singleton, @Module) and the generated modules. Use it when a definition is not picked up.

debugLogs = true prints the plugin internals (FIR and IR phases, module discovery). Use it when you report a plugin bug.

Both print lines prefixed with [Koin] at the severity set by logSeverity.

logSeverity and versionCheckSeverity​

Both accept "warning" (default) or "info".

koinCompiler {
    logSeverity = "info"
    versionCheckSeverity = "info"
}
  • logSeverity: severity of informational output (userLogs, debugLogs, the "no Koin entry point" notice, @Monitor summaries). Set it to "info" if your build uses allWarningsAsErrors, so this output does not fail the build.
  • versionCheckSeverity: severity of the warning shown when you build with a Kotlin version the plugin has not been verified against. It is separate so that muting log output does not also hide a compatibility risk. Set it to "info" only after you have checked that your Kotlin version works.

Neither option changes real diagnostics (KOIN-D001, KOIN-W003 and so on): they keep their own severity.

aiAssist​

When a build reports at least one Koin diagnostic, the plugin adds one line at the end of the compilation, pointing to the Kotzilla MCP Server, which an AI coding assistant can use to classify the error and propose a fix:

[Koin] → Fix with AI: set up Kotzilla MCP at https://kotzilla.io/koin-mcp

The line appears once per build, not per error. Set aiAssist = false to hide it.