{"record":{"id":"b320a08edfe43945","repo":"XTLS/Xray-core","slug":"unknown-command-cmd","errorCode":null,"errorMessage":"unknown command {cmd}","messagePattern":"unknown command (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"proxy/socks/protocol.go","lineNumber":182,"sourceCode":"\tif username != \"\" {\n\t\trequest.User = &protocol.MemoryUser{Email: username}\n\t}\n\tswitch cmd {\n\tcase cmdTCPConnect, cmdTorResolve, cmdTorResolvePTR:\n\t\t// We don't have a solution for Tor case now. Simply treat it as connect command.\n\t\trequest.Command = protocol.RequestCommandTCP\n\tcase cmdUDPAssociate:\n\t\tif !s.config.UdpEnabled {\n\t\t\twriteSocks5Response(writer, statusCmdNotSupport, net.AnyIP, net.Port(0))\n\t\t\treturn nil, nil, errors.New(\"UDP is not enabled.\")\n\t\t}\n\t\trequest.Command = protocol.RequestCommandUDP\n\tcase cmdTCPBind:\n\t\twriteSocks5Response(writer, statusCmdNotSupport, net.AnyIP, net.Port(0))\n\t\treturn nil, nil, errors.New(\"TCP bind is not supported.\")\n\tdefault:\n\t\twriteSocks5Response(writer, statusCmdNotSupport, net.AnyIP, net.Port(0))\n\t\treturn nil, nil, errors.New(\"unknown command \", cmd)\n\t}\n\n\trequest.Version = socks5Version\n\n\taddr, port, err := addrParser.ReadAddressPort(nil, reader)\n\tif err != nil {\n\t\treturn nil, nil, errors.New(\"failed to read address\").Base(err)\n\t}\n\trequest.Address = addr\n\trequest.Port = port\n\n\tresponseAddress := s.address\n\tresponsePort := s.port\n\tvar tempUDPConn *TempUDPConn\n\t//nolint:gocritic // Use if else chain for clarity\n\tif request.Command == protocol.RequestCommandUDP {\n\t\tif s.config.Address != nil {\n\t\t\t// Use configured IP as remote address in the response to UDP Associate","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/proxy/socks/protocol.go#L164-L200","documentation":"Thrown in handshake5 (proxy/socks/protocol.go:182) when the SOCKS5 command byte is not one of the implemented values: 0x01 (CONNECT), 0x02 handled separately as unsupported BIND, 0x03 (UDP ASSOCIATE), or the Tor extensions 0xF0/0xF1 (RESOLVE/RESOLVE_PTR, treated as CONNECT). Anything else gets statusCmdNotSupport and this error.","triggerScenarios":"Garbage command bytes from a malformed client, stream desynchronization after an earlier framing error, or a client using a non-standard command the server does not implement.","commonSituations":"Byte-offset bugs in custom clients; a previous protocol step consuming the wrong number of bytes so the CMD field lands on random data; non-SOCKS traffic (HTTP/TLS) hitting the port and being partially interpreted.","solutions":["Verify the client's request framing: VER 0x05, CMD 0x01/0x03, RSV 0x00, then the address.","Confirm the connection is actually speaking SOCKS5 to this port (protocol mismatch produces random command bytes).","Check that earlier negotiation steps (auth) consumed exactly the right number of bytes."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Client-side: whitelist known commands before sending\nvar cmd byte = 0x01\nswitch op {\ncase \"connect\": cmd = 0x01\ncase \"udp\": cmd = 0x03\ndefault: return fmt.Errorf(\"unsupported SOCKS5 operation %q\", op)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unknown command\") {\n    return fmt.Errorf(\"client sent an invalid SOCKS5 command byte; check framing\")\n}","preventionTips":["Only send CMD 0x01 or 0x03.","Byte-offset-test client framing to catch desync bugs early."],"tags":["socks","socks5","protocol","unsupported-command","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}