docs/reference/koin-core/troubleshooting.md
This guide covers debugging, common errors, and anti-patterns to avoid.
// Circular dependency - will fail at runtime
class ServiceA(val serviceB: ServiceB)
class ServiceB(val serviceA: ServiceA)
module {
single { ServiceA(get()) }
single { ServiceB(get()) } // ERROR: Circular dependency!
}
Break the cycle with lazy resolution:
class ServiceA : KoinComponent {
val serviceB: ServiceB by inject() // Lazy
}
class ServiceB : KoinComponent {
val serviceA: ServiceA by inject() // Lazy
}
module {
single { ServiceA() }
single { ServiceB() }
}
Refactor to remove the cycle (recommended):
// Extract shared logic
@Singleton
class SharedService
@Singleton
class ServiceA(private val shared: SharedService)
@Singleton
class ServiceB(private val shared: SharedService)
interface ServiceBContract {
fun doSomething()
}
@Singleton
class ServiceA(private val serviceB: ServiceBContract)
@Singleton
class ServiceB(private val serviceA: ServiceA) : ServiceBContract
startKoin {
// Set log level
printLogger(Level.DEBUG) // DEBUG, INFO, ERROR, NONE
modules(appModule)
}
verify()Validate all definitions can be resolved:
// In tests
@Test
fun `verify all modules`() {
appModule.verify() // Fails if any dependency is missing
}
:::info
Both verify() and checkModules() will be replaced by native compile-time safety in the Koin Compiler Plugin. See Module Verification for details.
:::
Missing Definition:
No definition found for class 'UserRepository'
Fix: Add the missing definition to a module
Circular Dependency:
Circular dependency detected
Fix: Use lazy injection or refactor (see above)
Scope Not Found:
No scope definition found for 'MyScope'
Fix: Ensure scope is created before accessing scoped dependencies
Multiple Definitions:
Multiple definitions found for type 'ApiClient'
Fix: Use qualifiers to distinguish between definitions
// Bad - Service locator pattern
class UserViewModel : ViewModel(), KoinComponent {
fun loadUser() {
val repository = get<UserRepository>() // Manual resolution
// ...
}
}
// Good - Constructor injection
class UserViewModel(
private val repository: UserRepository
) : ViewModel() {
fun loadUser() {
// Dependencies already injected
}
}
// Bad - Everything in one module
val appModule = module {
// 100+ definitions here
}
// Good - Organized modules
val databaseModule = module { /* ... */ }
val networkModule = module { /* ... */ }
val homeModule = module { /* ... */ }
// Bad - Qualifiers for different types
module {
single(named("user_repository")) { UserRepository() }
single(named("order_repository")) { OrderRepository() }
}
// Good - Types distinguish themselves
module {
singleOf(::UserRepository)
singleOf(::OrderRepository)
}
// Bad - Side effects in module
module {
single {
println("Loading database...") // Side effect
Database()
}
}
// Good - Pure dependency creation
module {
single { Database() }
}
// Bad - Dependencies hidden inside
class UserService {
private val api = ApiClient() // Hidden dependency
}
// Good - Explicit dependencies
class UserService(private val api: ApiClient)
get() calls inside classesverify() in tests - Catch missing definitions early