{"record":{"id":"b1363faf8455e671","repo":"containerd/containerd","slug":"hybrid-vsock-handshake-response-error-s","errorCode":null,"errorMessage":"hybrid vsock handshake response error: %s","messagePattern":"hybrid vsock handshake response error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/shim/util_unix.go","lineNumber":222,"sourceCode":"\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif _, err = fmt.Fprintln(conn, \"CONNECT\", port); err != nil {\n\t\t\tconn.Close()\n\t\t\treturn nil, err\n\t\t}\n\t\terrChan := make(chan error, 1)\n\t\tgo func() {\n\t\t\treader := bufio.NewReader(conn)\n\t\t\tresponse, err := reader.ReadString('\\n')\n\t\t\tif err != nil {\n\t\t\t\terrChan <- err\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif strings.Contains(response, \"OK\") {\n\t\t\t\terrChan <- nil\n\t\t\t} else {\n\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)","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/pkg/shim/util_unix.go#L204-L240","documentation":"In the hybrid vsock dialer (hvsock), after dialing the host-side unix socket the client writes 'CONNECT <port>' and reads a line back; if the response does not contain \"OK\", this error is returned. It means the hvsock proxy on the other end explicitly rejected or answered unexpectedly to the handshake.","triggerScenarios":"dialHybridVsock -> hybridVsockDialer connects to the hvsock bridge unix socket and receives a non-OK response line, e.g. when the requested vsock port is not registered on the host proxy, the guest service is not listening, or the proxy speaks an incompatible protocol.","commonSituations":"Connecting to a shim in a Hyper-V/hybrid-vsock setup before the guest-side listener started; wrong port in the hvsock address; mismatched or outdated host-side hvsock proxy version.","solutions":["Check the response text embedded in the error for the proxy's rejection reason.","Verify the hvsock port in the address matches the port the guest service is listening on.","Ensure the guest-side service/shim is fully started, then retry the dial.","Confirm the host hvsock proxy version is compatible with this client's CONNECT handshake."],"exampleFix":"// before\nconn, err := shim.AnonDialer(\"hvsock:///run/hvsock.sock:1234\", time.Second)\n// after: confirm guest listener, then use correct port\nconn, err := shim.AnonDialer(\"hvsock:///run/hvsock.sock:1024\", 5*time.Second)","handlingStrategy":"retry","validationCode":"// Before dialing, verify the target hvsock port is expected:\n// confirm the guest-side listener registered on `port` via your VM control plane,\n// e.g. check shim process logs or the host hvsock proxy's registered ports.","typeGuard":"func isHandshakeRejection(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"hybrid vsock handshake response error\")\n}","tryCatchPattern":"conn, err := shim.AnonDialer(hvAddr, timeout)\nif isHandshakeRejection(err) {\n\t// log response text from err, wait for guest service, then retry\n\ttime.Sleep(backoff)\n\tconn, err = shim.AnonDialer(hvAddr, timeout)\n}","preventionTips":["Only dial hvsock addresses after the guest service is confirmed started.","Keep guest shim and host hvsock proxy versions in lockstep.","Log the response payload embedded in the error to spot protocol mismatches."],"tags":["network","vsock","handshake","hvsock"],"backgroundTag":"handshake-rejected","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}