{"record":{"id":"1f8603381f029b01","repo":"hashicorp/nomad","slug":"failed-to-start-stream-v","errorCode":null,"errorMessage":"failed to start stream: %v","messagePattern":"failed to start stream: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pool/pool.go","lineNumber":486,"sourceCode":"START:\n\t// Try to get a conn first\n\tconn, err := p.acquire(region, addr)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to get conn: %v\", err)\n\t}\n\n\t// Get a client\n\tclient, err := conn.getRPCClient()\n\tif err != nil {\n\t\tp.clearConn(conn)\n\t\tconn.releaseUse()\n\n\t\t// Try to redial, possible that the TCP session closed due to timeout\n\t\tif retries == 0 {\n\t\t\tretries++\n\t\t\tgoto START\n\t\t}\n\t\treturn nil, nil, fmt.Errorf(\"failed to start stream: %v\", err)\n\t}\n\treturn conn, client, nil\n}\n\n// StreamingRPC is used to make an streaming RPC call.  Callers must\n// close the connection when done.\nfunc (p *ConnPool) StreamingRPC(region string, addr net.Addr) (net.Conn, error) {\n\tconn, err := p.acquire(region, addr)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get conn: %v\", err)\n\t}\n\n\ts, err := conn.session.Open()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to open a streaming connection: %v\", err)\n\t}\n\n\tif _, err := s.Write([]byte{byte(RpcStreaming)}); err != nil {","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pool/pool.go#L468-L504","documentation":"After acquiring a conn, getRPCClient obtains a yamux-backed RPC client from the connection. If that fails, it retries once (redialing, since the TCP session may have timed out); if the retry also fails, it returns 'failed to start stream: <err>'.","triggerScenarios":"pool.RPC -> getRPCClient where conn.getRPCClient errors on both the initial attempt and the single retry (retries>0 path).","commonSituations":"Stale yamux sessions killed by idle timeouts, server closing connections mid-handshake, heavy load causing stream setup failures twice in a row.","solutions":["Check inner error; session resets usually indicate idle timeouts — tune conn pool/keepalive settings","Verify server stability (crashes/OOM close sessions mid-handshake)","Retry the RPC at a higher level; persistent failure means investigate the network path"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := pool.RPC(region, addr, method, args, out)\nif err != nil && strings.Contains(err.Error(), \"failed to start stream\") {\n    // pool already retried once internally; retry once more after backoff\n    time.Sleep(250 * time.Millisecond)\n    return pool.RPC(region, addr, method, args, out)\n}","preventionTips":["Keep connections active or lower idle timeouts to avoid stale yamux sessions","Ensure server stability (session resets correlate with crashes/restarts)","Rate-limit to avoid yamux exhaustion under heavy load"],"tags":["rpc","yamux","stream"],"backgroundTag":"rpc-stream-setup-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}