{"record":{"id":"7dc3267ef1bd1e0c","repo":"containerd/containerd","slug":"timeout-waiting-for-hybrid-vsocket-handshake-of-s","errorCode":null,"errorMessage":"timeout waiting for hybrid vsocket handshake of %s:%d","messagePattern":"timeout waiting for hybrid vsocket handshake of (.+?):(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/shim/util_unix.go","lineNumber":240,"sourceCode":"\t\t\t\terrChan <- fmt.Errorf(\"hybrid vsock handshake response error: %s\", response)\n\t\t\t}\n\t\t}()\n\t\tselect {\n\t\tcase err = <-errChan:\n\t\t\tif err != nil {\n\t\t\t\tconn.Close()\n\t\t\t\t// When it is EOF, maybe the server side is not ready.\n\t\t\t\tif err == io.EOF {\n\t\t\t\t\tlog.G(context.Background()).Warnf(\"Read hybrid vsock got EOF, server may not ready\")\n\t\t\t\t\ttime.Sleep(retryInterval)\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t\treturn conn, nil\n\t\tcase <-timeoutCh:\n\t\t\tconn.Close()\n\t\t\treturn nil, fmt.Errorf(\"timeout waiting for hybrid vsocket handshake of %s:%d\", addr, port)\n\t\t}\n\t}\n\n}\n\nfunc dialVsock(address string) (net.Conn, error) {\n\tcontextIDString, portString, ok := strings.Cut(address, \":\")\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"invalid vsock address %s\", address)\n\t}\n\tcontextID, err := strconv.ParseUint(contextIDString, 10, 0)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse vsock context id %s, %v\", contextIDString, err)\n\t}\n\tif contextID > math.MaxUint32 {\n\t\treturn nil, fmt.Errorf(\"vsock context id %d is invalid\", contextID)\n\t}\n\tport, err := strconv.ParseUint(portString, 10, 0)","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/pkg/shim/util_unix.go#L222-L258","documentation":"hybridVsockDialer retries the CONNECT handshake up to a deadline (10 retry intervals within the timeout) and also races the response reader against a timeout channel. If the deadline elapses before an \"OK\" response is read, the connection is closed and this timeout error is returned. It means the host bridge never completed the handshake in time.","triggerScenarios":"AnonDialer/AnonReconnectDialer with an 'hvsock://' address where the proxy accepts the TCP/unix connection but never sends \"OK\" within the provided timeout — guest not ready, EOF-retry loop exhausting the deadline, or a hung proxy.","commonSituations":"Dialing a hybrid vsock shim immediately after VM start before the guest service binds; passing a too-short timeout (e.g. 100ms); slow guest boot under load.","solutions":["Increase the timeout parameter passed to AnonDialer/dialHybridVsock to cover guest startup time.","Verify the guest-side service on the requested port is running and accepting CONNECT requests.","Add caller-side retry with backoff around the dial for transient un readiness.","Check host proxy logs for stalled connections; restart the proxy if handshakes hang."],"exampleFix":"// before\nconn, err := shim.AnonDialer(addr, 100*time.Millisecond)\n// after\nconn, err := shim.AnonDialer(addr, 10*time.Second)","handlingStrategy":"retry","validationCode":"// Probe readiness with a generous timeout before the real dial:\nif !shim.CanConnect(hvAddr) { // internally uses a 100ms probe\n\ttime.Sleep(2 * time.Second) // guest not ready yet\n}","typeGuard":"func isHvsockHandshakeTimeout(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"timeout waiting for hybrid vsocket handshake\")\n}","tryCatchPattern":"var conn net.Conn\nvar err error\nfor i := 0; i < 5; i++ {\n\tconn, err = shim.AnonDialer(hvAddr, 10*time.Second)\n\tif err == nil || !isHvsockHandshakeTimeout(err) {\n\t\tbreak\n\t}\n\ttime.Sleep(time.Duration(1<<i) * time.Second)\n}","preventionTips":["Pass timeouts long enough to cover guest boot (seconds, not milliseconds).","Retry with exponential backoff around hvsock dials during VM startup.","Monitor the host hvsock proxy for hung connections and restart if stalled."],"tags":["network","timeout","hvsock","vsock"],"backgroundTag":"connection-timeout","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}