{"record":{"id":"b25b7b50a315ec65","repo":"XTLS/Xray-core","slug":"unknown-socks-version-version","errorCode":null,"errorMessage":"unknown Socks version: {version}","messagePattern":"unknown Socks version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"proxy/socks/protocol.go","lineNumber":248,"sourceCode":"func (s *ServerSession) Handshake(reader io.Reader, writer net.Conn) (*protocol.RequestHeader, *TempUDPConn, error) {\n\tbuffer := buf.StackNew()\n\tif _, err := buffer.ReadFullFrom(reader, 2); err != nil {\n\t\tbuffer.Release()\n\t\treturn nil, nil, errors.New(\"insufficient header\").Base(err)\n\t}\n\n\tversion := buffer.Byte(0)\n\tcmd := buffer.Byte(1)\n\tbuffer.Release()\n\n\tswitch version {\n\tcase socks4Version:\n\t\theader, err := s.handshake4(cmd, reader, writer)\n\t\treturn header, nil, err\n\tcase socks5Version:\n\t\treturn s.handshake5(cmd, reader, writer)\n\tdefault:\n\t\treturn nil, nil, errors.New(\"unknown Socks version: \", version)\n\t}\n}\n\n// ReadUsernamePassword reads Socks 5 username/password message from the given reader.\n// +----+------+----------+------+----------+\n// |VER | ULEN |  UNAME   | PLEN |  PASSWD  |\n// +----+------+----------+------+----------+\n// | 1  |  1   | 1 to 255 |  1   | 1 to 255 |\n// +----+------+----------+------+----------+\nfunc ReadUsernamePassword(reader io.Reader) (string, string, error) {\n\tbuffer := buf.StackNew()\n\tdefer buffer.Release()\n\n\tif _, err := buffer.ReadFullFrom(reader, 2); err != nil {\n\t\treturn \"\", \"\", err\n\t}\n\tnUsername := int32(buffer.Byte(1))\n","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/proxy/socks/protocol.go#L230-L266","documentation":"Returned by Handshake (proxy/socks/protocol.go:248) when the first byte of the connection is neither 0x04 (SOCKS4) nor 0x05 (SOCKS5). The server only speaks those two versions; anything else — often the first byte of HTTP ('G' 0x47, 'P' 0x50), TLS (0x16), or random data — is rejected.","triggerScenarios":"An HTTP client pointed at the SOCKS port (curl http://host:1080 uses HTTP proxy semantics, not SOCKS); HTTPS/TLS handshake bytes; a shadowsocks/vless client connected to a socks inbound; garbage probes.","commonSituations":"Using curl without the socks5h:// scheme (falls back to HTTP CONNECT against a SOCKS port); mixing up inbound protocols in the port map; tools defaulting to HTTP proxy mode.","solutions":["Point SOCKS-speaking clients at the port: curl -x socks5h://host:port, or configure the app's proxy type to SOCKS5.","If the traffic is actually HTTP, add an http inbound on that port instead of socks.","If the traffic is another protocol, expose the matching inbound (vless/shadowsocks/etc.) on the right port."],"exampleFix":"# before: HTTP-proxy style request against a SOCKS inbound\ncurl -x http://127.0.0.1:1080 https://example.com\n\n# after: SOCKS5 with remote DNS resolution\ncurl -x socks5h://127.0.0.1:1080 https://example.com","handlingStrategy":"validation","validationCode":"// Dispatch on the first wire byte before SOCKS parsing\nb := make([]byte, 1)\nif _, err := io.ReadFull(conn, b); err != nil { return err }\nswitch b[0] {\ncase 0x04, 0x05:\n    // continue with SOCKS handshake\ndefault:\n    return fmt.Errorf(\"not a SOCKS connection (first byte 0x%02X); check protocol/port mapping\", b[0])\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unknown Socks version\") {\n    return fmt.Errorf(\"protocol mismatch on SOCKS port: client is not speaking SOCKS4/5\")\n}","preventionTips":["Use socks5h:// scheme in curl and SOCKS type in app proxy settings.","Keep a port/protocol map of all inbounds to avoid cross-connections.","Prefer routing by separate loopback ports per protocol in tests."],"tags":["socks","protocol","version-mismatch","config","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}