Skip to content

Fix #2412 - drop displaced factory's cached singleton on override#2413

Open
glasser wants to merge 1 commit into
InsertKoinIO:mainfrom
glasser:glasser/fix-declare-leaves-cached-singleton
Open

Fix #2412 - drop displaced factory's cached singleton on override#2413
glasser wants to merge 1 commit into
InsertKoinIO:mainfrom
glasser:glasser/fix-declare-leaves-cached-singleton

Conversation

@glasser
Copy link
Copy Markdown

@glasser glasser commented May 8, 2026

Fixes #2412.

When InstanceRegistry.saveMapping overrides an existing mapping (e.g. via koin.declare(...)), the displaced InstanceFactory was left with its value still cached. Because Module.mappings shares factory references with the registry, the orphan survived stopKoin() (which only iterates _instances) and was re-installed on the next startKoin { modules(sameModule) }, leaking the previous lifecycle's singleton into the new one.

This is a long-standing latent bug — present in every released koin version going back to 3.x. It only manifests when the same Module instance is loaded across multiple stopKoin/startKoin cycles after a declare override has populated the displaced factory's cache. That combination is rare in production but routine in test setups; in particular it became newly visible in late-2024 / 2025 to users of kotest-extensions-koin after kotest 6 turned Spec.extensions from a function into a property. See the issue for the full diagnosis, the kotest-6 connection, and a public reproduction repo.

The fix is two lines in saveMapping's override branch: when _instances[mapping] is being replaced by a different factory, call dropAll() on the displaced one before overwriting. The displaced !== factory guard preserves the no-op behavior when the same factory is re-registered (e.g., loading an already-loaded module).

Test

Adds DeclareOverrideDropsCachedSingleTest covering the regression: declare a fresh override on top of a module-owned single, mutate the singleton, stopKoin, then startKoin with the same module instance — get<T>() must return a fresh singleton.

  • Without the patch the test fails on the assertNotSame(first, second) and assertEquals(0, second.value) assertions.
  • With the patch the new test passes, and the full :core:koin-core:jvmTest is green (284/284, including all of DeclareInstanceTest — no behavior change for documented declare/override semantics, only for the latent cache leak).

…override

When `InstanceRegistry.saveMapping` replaces an existing mapping (e.g.
via `koin.declare(...)`), the displaced `InstanceFactory` was left with
its cached value still set. Because `Module.mappings` shares factory
references with the registry, the orphan survives `stopKoin()` — which
iterates `_instances`, never the orphan — and is re-installed on the
next `startKoin { modules(sameModule) }`, returning a stale singleton
from the previous lifecycle.

Fix: in `saveMapping`'s override branch, call `dropAll()` on the
displaced factory before overwriting. The `displaced !== factory`
guard preserves the no-op behavior when the same factory is
re-registered (e.g. loading an already-loaded module).

Adds `DeclareOverrideDropsCachedSingleTest` as a regression: declare a
fresh override on top of a module-owned `single`, mutate the singleton,
`stopKoin`, then `startKoin` with the same module — the next `get<T>()`
must return a fresh singleton.

See InsertKoinIO#2412 for the full diagnosis, including the kotest-6 interaction
that newly exposes the bug.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant