{"record":{"id":"5283efbf08d89d4e","repo":"go-delve/delve","slug":"stub-exited-while-attempting-to-connect-v","errorCode":null,"errorMessage":"stub exited while attempting to connect: %v","messagePattern":"stub exited while attempting to connect: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/proc/gdbserial/gdbserver.go","lineNumber":320,"sourceCode":"\t\t\treturn nil, err\n\t\t}\n\t\treturn nil, fmt.Errorf(\"stub exited while waiting for connection: %v\", status)\n\t}\n}\n\n// Dial attempts to connect to the stub.\nfunc (p *gdbProcess) Dial(addr string, path, cmdline string, pid int, debugInfoDirs []string, stopReason proc.StopReason) (*proc.TargetGroup, error) {\n\tfor {\n\t\tconn, err := net.Dial(\"tcp\", addr)\n\t\tif err == nil {\n\t\t\treturn p.Connect(conn, path, cmdline, pid, debugInfoDirs, stopReason)\n\t\t}\n\t\tselect {\n\t\tcase status := <-p.waitChan:\n\t\t\tif err := checkRosettaExpensive(); err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"stub exited while attempting to connect: %v\", status)\n\t\tdefault:\n\t\t}\n\t\ttime.Sleep(time.Second)\n\t}\n}\n\n// Connect connects to a stub and performs a handshake.\n//\n// Path and pid are, respectively, the path to the executable of the target\n// program and the PID of the target process, both are optional, however\n// some stubs do not provide ways to determine path and pid automatically\n// and Connect will be unable to function without knowing them.\nfunc (p *gdbProcess) Connect(conn net.Conn, path, cmdline string, pid int, debugInfoDirs []string, stopReason proc.StopReason) (*proc.TargetGroup, error) {\n\tp.conn.conn = conn\n\tp.conn.pid = pid\n\terr := p.conn.handshake(p.regnames)\n\tif err != nil {\n\t\tconn.Close()","sourceCodeStart":302,"sourceCodeEnd":338,"githubUrl":"https://github.com/go-delve/delve/blob/a23773e6c31361e43246bc43a424ee009679b174/pkg/proc/gdbserial/gdbserver.go#L302-L338","documentation":"gdbProcess.Dial connects to an already-running gdbserial stub. While waiting for the stub to become connectable it polls the connection in a loop; if at any point the wait channel reports the stub process has terminated, Dial aborts with 'stub exited while attempting to connect' wrapping the exit status.","triggerScenarios":"Calling debugger.Dial()/connect to a headless stub whose process died while Delve was retrying the connection loop — the stub crashed after printing its port, was killed externally, or exited because another client already connected.","commonSituations":"Connecting to a `dlv --headless`/lldb-server process that crashed or was terminated before the client attached; two clients racing to connect to the same stub; stale address/port reused after the stub exited; container/CI environments reaping the stub process.","solutions":["Check the wrapped exit status and inspect the stub's output/logs to see why it terminated before the connection completed.","Verify the stub process is still alive (ps) at the address you're dialing, and restart it if needed, then connect promptly.","Ensure only one client connects; a stub typically serves a single connection and exits after another client attaches.","Use a stable, supported stub version and environment (matching Delve and OS/arch), especially in containers/CI."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before dialing, confirm the stub is listening and alive\nconn, err := net.DialTimeout(\"tcp\", addr, 2*time.Second)\nif err != nil {\n    return fmt.Errorf(\"no stub listening at %s: %w\", addr, err)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"tg, err := dbg.Dial(addr, ...)\nif err != nil && strings.Contains(err.Error(), \"stub exited while attempting to connect\") {\n    return fmt.Errorf(\"target stub terminated before connection: %w; restart the headless session\", err)\n}","preventionTips":["Connect promptly after the stub reports its listening port","Allow only one client per stub session","Monitor the stub process (ps / wait) and surface its logs on failure","Use matching Delve/stub versions in containers and CI"],"tags":["gdbserial","connection","process-exit","remote-debugging"],"backgroundTag":"stub-exited-before-connection","analyzedSha":"a23773e6c31361e43246bc43a424ee009679b174","analyzedAt":"2026-08-31T15:12:45.221Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}