{"record":{"id":"066e39630981ac1b","repo":"tailscale/tailscale","slug":"incompatible-socks-version","errorCode":null,"errorMessage":"incompatible SOCKS version","messagePattern":"incompatible SOCKS version","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"net/socks5/socks5.go","lineNumber":492,"sourceCode":"\tportInt, err := strconv.Atoi(portStr)\n\tif err != nil {\n\t\treturn \"\", 0, err\n\t}\n\tif portInt < 0 || portInt > 65535 {\n\t\treturn \"\", 0, fmt.Errorf(\"invalid port number %d\", portInt)\n\t}\n\treturn host, uint16(portInt), nil\n}\n\n// parseClientGreeting parses a request initiation packet.\nfunc parseClientGreeting(r io.Reader, authMethod byte) error {\n\tvar hdr [2]byte\n\t_, err := io.ReadFull(r, hdr[:])\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not read packet header\")\n\t}\n\tif hdr[0] != socks5Version {\n\t\treturn fmt.Errorf(\"incompatible SOCKS version\")\n\t}\n\tcount := int(hdr[1])\n\tmethods := make([]byte, count)\n\t_, err = io.ReadFull(r, methods)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not read methods\")\n\t}\n\tif slices.Contains(methods, authMethod) {\n\t\treturn nil\n\t}\n\treturn fmt.Errorf(\"no acceptable auth methods\")\n}\n\nfunc parseClientAuth(r io.Reader) (usr, pwd string, err error) {\n\tvar hdr [2]byte\n\tif _, err := io.ReadFull(r, hdr[:]); err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"could not read auth packet header\")\n\t}","sourceCodeStart":474,"sourceCodeEnd":510,"githubUrl":"https://github.com/tailscale/tailscale/blob/57c3357fdb542d26c6f9e9f0b815ae5077e63d77/net/socks5/socks5.go#L474-L510","documentation":"The first greeting byte (VER) was not 5, so the peer is not speaking SOCKS5 on this connection. Classic causes: a SOCKS4/4a client (VER=4), an HTTP client whose request line starts with 'G' (0x47), or another protocol entirely such as an SSH banner ('S' = 0x53). The server rejects the connection before any method negotiation reply is meaningful.","triggerScenarios":"curl -x socks4:// pointed at this server; an HTTP request sent straight to the SOCKS port; an HTTPS client connecting without a CONNECT path; a SOCKS client library with a broken version byte; one port accidentally shared by two different proxy services.","commonSituations":"Misconfigured proxy scheme in browsers or curl (http vs socks4 vs socks5); pointing an HTTP proxy setting at tailscaled's SOCKS5 port; legacy tooling that only speaks SOCKS4.","solutions":["Switch the client to SOCKS5 (curl socks5:// or socks5h://, browsers SOCKS5 proxy type, libraries SOCKS5 mode).","If the client must stay SOCKS4, put a translating proxy in front or extend parseClientGreeting to accept version 4.","Double-check that the port the client targets is really the SOCKS5 listener."],"exampleFix":"# before\ncurl -x socks4://127.0.0.1:1055 https://example.com\n\n# after\ncurl -x socks5h://127.0.0.1:1055 https://example.com","handlingStrategy":"validation","validationCode":"// client side: assert SOCKS5 before connecting through a stack that picks the version\nif !strings.HasPrefix(scheme, \"socks5\") {\n\treturn fmt.Errorf(\"refusing to speak %s to a SOCKS5 server\", scheme)\n}","typeGuard":"func isVersionMismatch(err error) bool {\n\treturn strings.Contains(err.Error(), \"incompatible SOCKS version\")\n}","tryCatchPattern":"if err := conn.Run(); err != nil {\n\tif isVersionMismatch(err) {\n\t\ts.logf(\"non-SOCKS5 client %v connected\", c.RemoteAddr())\n\t\treturn // expected for misconfigured clients\n\t}\n\ts.logf(\"client connection failed: %v\", err)\n}","preventionTips":["Standardize on socks5h:// URLs so hostnames resolve at the proxy.","Do not share one listen port between HTTP and SOCKS services.","Reject SOCKS4-only tooling or front it with a protocol translator."],"tags":["socks5","go","protocol-mismatch","version","handshake"],"backgroundTag":"socks-version-mismatch","analyzedSha":"57c3357fdb542d26c6f9e9f0b815ae5077e63d77","analyzedAt":"2026-08-18T08:17:25.280Z","contentChangedAt":"2026-08-18T08:17:25.280Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}