{"record":{"id":"43a4808d64652615","repo":"go-delve/delve","slug":"thread-blocked","errorCode":null,"errorMessage":"thread blocked","messagePattern":"thread blocked","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkg/proc/gdbserial/gdbserver_conn.go","lineNumber":692,"sourceCode":"\t\t\treturn nil\n\t\tcase childSignal: // stop on debugserver but SIGCHLD on lldb-server/linux\n\t\t\tif conn.isDebugserver {\n\t\t\t\treturn nil\n\t\t\t}\n\t\tcase debugServerTargetExcBadAccess, debugServerTargetExcBadInstruction, debugServerTargetExcArithmetic, debugServerTargetExcEmulation, debugServerTargetExcSoftware, debugServerTargetExcBreakpoint:\n\t\t\tif ignoreFaultSignal {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\treturn machTargetExcToError(sig)\n\t\tdefault:\n\t\t\t// delay propagation of any other signal to until after the stepping is done\n\t\t\tth.sig = sig\n\t\t\tsig = 0\n\t\t}\n\t}\n}\n\nvar errThreadBlocked = errors.New(\"thread blocked\")\n\nfunc (conn *gdbConn) waitForvContStop(context, threadID string, tu *threadUpdater) (stopPacket, error) {\n\tcount := 0\n\tfailed := false\n\tfor {\n\t\tconn.conn.SetReadDeadline(time.Now().Add(heartbeatInterval))\n\t\tresp, err := conn.recv(nil, context, false)\n\t\tconn.conn.SetReadDeadline(time.Time{})\n\t\tif neterr, isneterr := err.(net.Error); isneterr && neterr.Timeout() {\n\t\t\t// Debugserver sometimes forgets to inform us that inferior stopped,\n\t\t\t// sending this status request after a timeout helps us get unstuck.\n\t\t\t// Debugserver will not respond to this request unless inferior is\n\t\t\t// already stopped.\n\t\t\tif conn.isDebugserver {\n\t\t\t\tconn.send([]byte(\"$?\"))\n\t\t\t}\n\t\t\tif count > 1 && context == \"singlestep\" {\n\t\t\t\tfailed = true","sourceCodeStart":674,"sourceCodeEnd":710,"githubUrl":"https://github.com/go-delve/delve/blob/a23773e6c31361e43246bc43a424ee009679b174/pkg/proc/gdbserial/gdbserver_conn.go#L674-L710","documentation":"errThreadBlocked is an internal sentinel error returned by waitForvContStop. When the vCont continue/step is issued and a stop packet indicates the thread could not run because it is blocked (e.g. blocked in a syscall or waiting on another thread's stop), the connection uses this error to signal that state to its caller, which typically retries or resolves the thread state.","triggerScenarios":"Calling ContinueOnce/step on the gdbserial backend when waitForvContStop reads a stop reply showing the thread is blocked rather than truly stopped at a signal; common with all-stop mode where one thread cannot resume until others stop.","commonSituations":"Stepping a thread that is parked in a blocking syscall (read/write/futex); debugging multithreaded programs via lldb-server/debugserver where thread scheduling interlocks; single-thread resume requests during process-wide stops.","solutions":["Retry the continue/step — Delve handles this internally; if it surfaces, simply continue again","Resume other threads first or use process-wide continue instead of stepping a single thread","Check whether the target thread is stuck in a syscall and let the program progress to a runnable state","If it recurs persistently, restart the session; some stub versions have blocked-thread reporting bugs"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := sess.Step(); err != nil {\n    if strings.Contains(err.Error(), \"thread blocked\") {\n        // thread is in a blocking syscall; wait and retry or continue all threads\n        time.Sleep(100 * time.Millisecond)\n        err = sess.Continue()\n    }\n}","preventionTips":["Prefer process-wide continue over stepping individual threads parked in syscalls","Step on threads in runnable user code, not inside blocking syscalls","Update lldb-server/debugserver to reduce all-stop scheduling quirks"],"tags":["gdbserial","threading","vcont","debugger"],"backgroundTag":"thread-blocked-stop","analyzedSha":"a23773e6c31361e43246bc43a424ee009679b174","analyzedAt":"2026-08-31T15:12:45.221Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}