{"record":{"id":"37d341f828f81149","repo":"ginuerzh/gost","slug":"peer-connect-failure","errorCode":null,"errorMessage":"peer connect failure","messagePattern":"peer connect failure","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"forward.go","lineNumber":578,"sourceCode":"\t\tlog.Log(\"[rtcp] SOCKS5 BIND reply: \", err)\n\t\treturn nil, err\n\t}\n\tconn.SetReadDeadline(time.Time{})\n\tif rep.Rep != gosocks5.Succeeded {\n\t\tlog.Logf(\"[rtcp] bind on %s failure\", l.addr)\n\t\treturn nil, fmt.Errorf(\"Bind on %s failure\", l.addr.String())\n\t}\n\tlog.Logf(\"[rtcp] BIND ON %s OK\", rep.Addr)\n\n\t// second reply, peer connected\n\trep, err = gosocks5.ReadReply(conn)\n\tif err != nil {\n\t\tlog.Log(\"[rtcp]\", err)\n\t\treturn nil, err\n\t}\n\tif rep.Rep != gosocks5.Succeeded {\n\t\tlog.Logf(\"[rtcp] peer connect failure: %d\", rep.Rep)\n\t\treturn nil, errors.New(\"peer connect failure\")\n\t}\n\n\tlog.Logf(\"[rtcp] PEER %s CONNECTED\", rep.Addr)\n\treturn conn, nil\n}\n\nfunc (l *tcpRemoteForwardListener) Addr() net.Addr {\n\tif l.ln != nil {\n\t\treturn l.ln.Addr()\n\t}\n\treturn l.addr\n}\n\nfunc (l *tcpRemoteForwardListener) Close() error {\n\tif l.ln != nil {\n\t\treturn l.ln.Close()\n\t}\n","sourceCodeStart":560,"sourceCodeEnd":596,"githubUrl":"https://github.com/ginuerzh/gost/blob/a33fdbf4c98034f4bfeeaea9868909822b9c526d/forward.go#L560-L596","documentation":"waitConnectSOCKS5 returns 'peer connect failure' when the remote SOCKS5 relay answered the CONNECT for the peer (client behind NAT) with a non-Succeeded reply code. The remote relay reached the relay, but the relay could not establish the connection to the peer endpoint (rep.Rep carries the SOCKS5 failure reason).","triggerScenarios":"Accepting a remote port-forward (rtcp) where the remote server's SOCKS5 CONNECT reply rep.Rep != gosocks5.Succeeded — e.g. host unreachable, connection refused, or not allowed on the remote side.","commonSituations":"NAT hole-punching for reverse tunnels where the client-side peer is down, firewall blocks the remote relay to peer hop, wrong peer port in rtcp config, remote relay lacks outbound access.","solutions":["Check the remote log line '[rtcp] peer connect failure: <code>' for the exact SOCKS5 reply code","Verify the peer (client behind NAT) is running and listening on the expected port","Fix firewall/NAT rules on the peer side allowing the relay's inbound connection","Confirm remote relay node connectivity and that its egress permits reaching the peer"],"exampleFix":"// before\nconn, err := l.waitConnectSOCKS5(...) // opaque failure\n// after\nconn, err := l.waitConnectSOCKS5(...)\nif err != nil {\n    if err.Error() == \"peer connect failure\" {\n        // inspect remote logs for rep.Rep; retry after peer is reachable\n        return nil, fmt.Errorf(\"peer connect failure (rep=%d): retry after peer reachable\", lastRep)\n    }\n    return nil, err\n}","handlingStrategy":"retry","validationCode":"// before accepting a rtcp tunnel, verify peer reachability\nconn, err := net.DialTimeout(\"tcp\", peerAddr, 5*time.Second)\nif err != nil {\n    return fmt.Errorf(\"peer %s not reachable before tunnel setup: %w\", peerAddr, err)\n}","typeGuard":"func isPeerConnectFailure(err error) bool {\n    return err != nil && err.Error() == \"peer connect failure\"\n}","tryCatchPattern":"conn, err := l.Accept()\nif err != nil {\n    if isPeerConnectFailure(err) {\n        // inspect remote 'peer connect failure: <rep>' log, wait, then retry\n        time.Sleep(backoff)\n        return retry()\n    }\n    return err\n}","preventionTips":["Health-check the peer endpoint before registering the remote forward","Read the SOCKS5 reply code in remote logs to distinguish refused vs unreachable vs forbidden","Keep peers listening and reachable through their NAT (keepalive/heartbeat)","Configure retries with backoff instead of treating a single failure as fatal"],"tags":["socks5","go","nat-traversal","port-forward","peer-connection"],"backgroundTag":"socks5-connect-failed","analyzedSha":"a33fdbf4c98034f4bfeeaea9868909822b9c526d","analyzedAt":"2026-09-02T22:15:54.506Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}