{"id":787,"date":"2026-10-08T13:50:00","date_gmt":"2026-10-08T11:50:00","guid":{"rendered":"https:\/\/grindloop.io\/blog\/?p=787"},"modified":"2026-10-07T22:33:59","modified_gmt":"2026-10-07T20:33:59","slug":"kotlin-mutex-withlock-deadlock","status":"publish","type":"post","link":"https:\/\/grindloop.ai\/blog\/kotlin-mutex-withlock-deadlock\/","title":{"rendered":"Kotlin Mutex withLock Deadlock: Why a Nested withLock Hangs Forever"},"content":{"rendered":"

A Mutex withLock deadlock happens when code holding a Mutex<\/code> calls a function that locks it again. Two causes stack up. First, the kotlinx.coroutines Mutex<\/code> is non-reentrant. The holder gets no pass. Its second lock<\/code> waits like any other caller. It’s waiting on itself, so it never gets the lock. Second, the hang is silent. A suspended coroutine doesn’t block a thread. So the main thread keeps drawing frames and no ANR fires. Nothing throws. lock<\/code> has no timeout either. The screen just shows a spinner forever. The usual trigger is a migration from @Synchronized<\/code>. That lock is reentrant, so the nested call used to work. The fix is structural. Keep withLock<\/code> only in the public entry points. Move the shared work into a private function that assumes the caller holds the lock. Then call that private function from inside the lock.<\/p>\n\n

A token store that never returns its first token<\/h2>\n\n

The running example is an auth token cache. Many requests need a token at once. Only one refresh may run. The Mutex<\/code> serializes them. validToken()<\/code> locks, checks expiry and refreshes if needed. refresh()<\/code> is public too, because a 401 handler calls it directly. So it locks as well. The code was a @Synchronized<\/code> class before the move to suspend functions.<\/p>\n\n\n

import kotlinx.coroutines.*\nimport kotlinx.coroutines.sync.Mutex\nimport kotlinx.coroutines.sync.withLock\n\nclass TokenStore(private val api: AuthApi) {\n    private val mutex = Mutex()\n    private var token: String? = null\n    private var expiresAt = 0L\n\n    suspend fun validToken(): String = mutex.withLock {\n        if (token == null || System.currentTimeMillis() >= expiresAt) {\n            refresh()\n        }\n        token!!\n    }\n\n    suspend fun refresh() = mutex.withLock {\n        val fresh = api.refresh()\n        token = fresh\n        expiresAt = System.currentTimeMillis() + 60_000\n    }\n}\n\nclass AuthApi {\n    suspend fun refresh(): String { delay(50); return \"tok-1\" }\n}\n\nfun main() = runBlocking {\n    val store = TokenStore(AuthApi())\n    val job = launch {\n        println(\"requesting token\")\n        println(\"got ${store.validToken()}\")\n    }\n    delay(2_000)\n    println(\"after 2s: job.isActive=${job.isActive}, isCompleted=${job.isCompleted}\")\n    job.cancel()\n    job.join()\n    println(\"cancelled: ${job.isCancelled}\")\n}<\/pre>\n\n\n
Compiled with kotlinc<\/code> 2.4.20 against kotlinx.coroutines 1.10.2, it prints this:<\/p>\n\n\n
requesting token\nafter 2s: job.isActive=true, isCompleted=false\ncancelled: true<\/pre>\n\n\n
The line got ...<\/code> never appears. The fake API answers in 50 ms, yet two seconds later the job is still active. launch<\/code> inside runBlocking<\/code> runs on the same single thread as main<\/code>. That thread still ran the delay<\/code>, the print and the cancel. On Android, that thread would be the main thread. It would keep handling taps and frames while the token request never finishes.<\/p>\n\n
A Mutex withLock deadlock happens because the holder waits on itself<\/h2>\n\n
The Mutex API docs<\/a> state it directly. The mutex is non-reentrant. Calling lock<\/code> suspends the caller even from the thread or coroutine that holds the lock. Walk validToken()<\/code> through that rule:<\/p>\n\n
    \n
  1. validToken()<\/code> calls withLock<\/code>. The mutex is free, so the coroutine takes it.<\/li>\n
  2. The token is null, so it calls refresh()<\/code>.<\/li>\n
  3. refresh()<\/code> calls withLock<\/code> on the same mutex. The mutex is locked, so the coroutine suspends and joins the wait queue.<\/li>\n
  4. The lock can only be released when the outer withLock<\/code> block ends. That block is waiting for refresh()<\/code> to return. Neither side can move.<\/li>\n<\/ol>\n\n
    Java’s synchronized<\/code> works differently. It tracks the owning thread, so the same thread can enter again. That’s why the old @Synchronized<\/code> version worked. A coroutine has no fixed thread to track. It can resume on a different thread after any suspension. Making the mutex reentrant would need a stable coroutine identity instead.<\/p>\n\n
    The library team has declined to add one. A user filed kotlinx.coroutines issue #1686<\/a> in December 2019. It asked for a reentrant lock keyed on the current Job<\/code>. Roman Elizarov of JetBrains closed it the same day. He pointed out that withContext<\/code> and coroutineScope<\/code> create a new Job<\/code> without starting a new coroutine. So a Job<\/code> isn’t a reliable identity. He called coroutines “too ephemeral” for a reentrant lock. The issue is closed but still drew comments through 2024.<\/p>\n\n
    The hang is silent because suspension blocks no thread<\/h2>\n\n
    The second cause decides how long the bug survives. A thread deadlock in Java is loud. In the classic two-lock case, both threads sit in BLOCKED<\/code>. A jstack<\/code> dump reports a Java-level deadlock. On Android, a main thread blocked for 5 seconds on input triggers an ANR. The Android ANR docs<\/a> list that input-dispatch timeout as the common foreground trigger.<\/p>\n\n
    A suspended coroutine triggers none of this. It’s a continuation sitting in the mutex’s wait queue. No thread is parked on it. The thread dump shows idle threads. The ANR watchdog sees a main thread that answers input on time. The lock<\/code> docs<\/a> describe it as suspending until the lock is acquired, with no timeout parameter. So the wait has no end.<\/p>\n\n
    Only cancellation ends it. The same docs say lock<\/code> is cancellable. A waiting caller resumes with CancellationException<\/code>. That matches the last line of the repro. In an app, viewModelScope<\/code> is canceled when the ViewModel is cleared. So the bug looks like a slow network that recovers after the user leaves the screen. To see the real state, pause in the debugger. Kotlin’s coroutine debugging tutorial<\/a> describes a Coroutines tab that lists each coroutine with its status. A coroutine stuck in this deadlock would show there as suspended.<\/p>\n\n
    Lock once at the entry point and call a private unlocked function<\/h2>\n\n
    The fix separates two jobs. The public functions acquire the lock. A private function does the work and assumes the caller already holds the lock. The Locked<\/code> suffix is only a naming habit. It warns the next reader not to call it from outside.<\/p>\n\n\n
    import kotlinx.coroutines.*\nimport kotlinx.coroutines.sync.Mutex\nimport kotlinx.coroutines.sync.withLock\nimport java.util.concurrent.atomic.AtomicInteger\n\nclass TokenStore(private val api: AuthApi) {\n    private val mutex = Mutex()\n    private var token: String? = null\n    private var expiresAt = 0L\n\n    suspend fun validToken(): String = mutex.withLock {\n        if (token == null || System.currentTimeMillis() >= expiresAt) {\n            refreshLocked()\n        }\n        token!!\n    }\n\n    suspend fun refresh() = mutex.withLock { refreshLocked() }\n\n    \/\/ Caller must hold mutex.\n    private suspend fun refreshLocked() {\n        val fresh = api.refresh()\n        token = fresh\n        expiresAt = System.currentTimeMillis() + 60_000\n    }\n}\n\nclass AuthApi {\n    val calls = AtomicInteger()\n    suspend fun refresh(): String { delay(50); return \"tok-${calls.incrementAndGet()}\" }\n}\n\nfun main() = runBlocking {\n    val api = AuthApi()\n    val store = TokenStore(api)\n    val tokens = List(10) { async(Dispatchers.Default) { store.validToken() } }.awaitAll()\n    println(\"tokens=${tokens.toSet()} refreshCalls=${api.calls.get()}\")\n    store.refresh()\n    println(\"after forced refresh: ${store.validToken()} refreshCalls=${api.calls.get()}\")\n}<\/pre>\n\n\n\n
    tokens=[tok-1] refreshCalls=1\nafter forced refresh: tok-2 refreshCalls=2<\/pre>\n\n\n
    Ten coroutines on Dispatchers.Default<\/code> asked for a token at once. All ten got tok-1<\/code>. The API was called once. The first caller refreshed while holding the lock. The other nine waited in the queue. Each then saw a fresh token and skipped the refresh. The forced refresh from the 401 path still works. It still runs under the lock.<\/p>\n\n
    The fix keeps one rule. Only public functions call withLock<\/code>. They never call each other while holding it. If validToken()<\/code> grows a new helper, the helper gets the Locked<\/code> treatment too. For a different mutex guarding pagination state, see our pagination race condition post<\/a>. There the bug is a missing lock.<\/p>\n\n
    The answer to give when the interviewer says the request never returns<\/h2>\n\n
    This snippet fits a bug-squash or debugging round. The symptom is vague on purpose. Nothing crashes. The test just times out. Our Android debugging interview post<\/a> covers how that round is scored. Here’s the explanation to give.<\/p>\n\n
      \n
    1. Name the cycle. validToken()<\/code> holds the mutex and calls refresh()<\/code>. That function locks the same mutex. The inner call waits for a lock its own caller holds.<\/li>\n
    2. Name the rule behind it. Mutex<\/code> is non-reentrant by design. synchronized<\/code> is reentrant because it tracks a thread. A coroutine has no fixed thread, so the library won’t guess an owner.<\/li>\n
    3. Explain why nothing failed loudly. The coroutine is suspended, not blocked. No thread is stuck, so no ANR and no thread-dump deadlock. lock<\/code> waits until cancellation.<\/li>\n
    4. Give the fix. Lock only at public entry points. Move the shared body into a private function that requires the caller to hold the lock. Call that function from both entry points.<\/li>\n
    5. Offer a test. Call validToken()<\/code> on an empty cache inside withTimeout<\/code>. The nested lock then fails the test in seconds instead of hanging it.<\/li>\n<\/ol>\n\n
      Point 3 explains why the bug reached production. It also shows you know how suspension differs from blocking.<\/p>\n\n
      Five fixes that hide the hang or move it somewhere else<\/h2>\n\n
      Each of these came up against the token store. The ones with a run behind them used the same compiler and library versions as above.<\/p>\n\n