{"record":{"id":"b1056f78d7ef6a5d","repo":"fatedier/frp","slug":"received-json-udp-packet-after-binary-codec-negoti","errorCode":null,"errorMessage":"received JSON UDP packet after binary codec negotiation","messagePattern":"received JSON UDP packet after binary codec negotiation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/msg/udp_binary.go","lineNumber":238,"sourceCode":"\ntype V2BinaryUDPPacketReadWriter struct {\n\tconn *wire.Conn\n}\n\nfunc NewV2BinaryUDPPacketReadWriter(rw io.ReadWriter) *V2BinaryUDPPacketReadWriter {\n\treturn &V2BinaryUDPPacketReadWriter{conn: wire.NewConn(rw)}\n}\n\nfunc (rw *V2BinaryUDPPacketReadWriter) ReadMsg() (Message, error) {\n\tframe, err := rw.conn.ReadFrame()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif isV2MessageType(frame, V2TypeUDPPacketBinary) {\n\t\treturn decodeV2BinaryUDPPacketFrame(frame)\n\t}\n\tif isV2MessageType(frame, V2TypeUDPPacket) {\n\t\treturn nil, fmt.Errorf(\"received JSON UDP packet after binary codec negotiation\")\n\t}\n\treturn DecodeV2MessageFrame(frame)\n}\n\nfunc (rw *V2BinaryUDPPacketReadWriter) ReadMsgInto(out Message) error {\n\tframe, err := rw.conn.ReadFrame()\n\tif err != nil {\n\t\treturn err\n\t}\n\tif packetOut, ok := out.(*UDPPacket); ok {\n\t\tif !isV2MessageType(frame, V2TypeUDPPacketBinary) {\n\t\t\treturn unexpectedV2UDPPacketType(frame)\n\t\t}\n\t\tpacket, err := decodeV2BinaryUDPPacketFrame(frame)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\t*packetOut = *packet","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/pkg/msg/udp_binary.go#L220-L256","documentation":"V2BinaryUDPPacketReadWriter.ReadMsg received a JSON-encoded UDP packet (message type 13, V2TypeUDPPacket) after both sides had already negotiated the binary UDP packet codec. With the binary codec active, all UDP packets must arrive as type 19 (V2TypeUDPPacketBinary); a type-13 packet means the peer ignored or missed the codec negotiation. The connection is left in an inconsistent state, so the error should be treated as fatal.","triggerScenarios":"ReadMsg() on a work connection where frps and frpc disagreed on udpPacketCodec — e.g. the client sent binary packets while the server (older version, or config not applying) still emits JSON UDPPacket frames.","commonSituations":"frps upgraded but frpc not (binary codec exists only in newer versions); udpPacketCodec setting not propagated to the visitor side of an frp tunnel; a proxy between the peers strips or rewrites the negotiation.","solutions":["Align versions: run the same frp release on both frpc and frps.","Check that udpPacketCodec = \"binary\" (or equivalent) is consistently configured on both ends of the tunnel, including visitor configs.","If mixed versions are unavoidable, unset the binary UDP packet codec so both sides use the JSON codec.","Restart the work connection after fixing config; the codec is chosen at connection setup."],"exampleFix":"# before\n# frpc.toml sets binary UDP codec, frps is an older release\n\n# after\n# upgrade frps to the matching release, or on frpc.toml remove:\n# udpPacketCodec = \"binary\"","handlingStrategy":"try-catch","validationCode":"// ensure both ends agree before establishing the work connection\nif udpPacketCodec != \"\" && wireProtocol != wire.ProtocolV2 {\n\treturn errors.New(\"binary UDP codec requires v2 wire protocol on both ends\")\n}","typeGuard":null,"tryCatchPattern":"if _, err := rw.ReadMsg(); err != nil {\n\tif strings.Contains(err.Error(), \"after binary codec negotiation\") {\n\t\t// peer did not adopt the binary codec: fix version/config on the peer, then reconnect\n\t\tconn.Close()\n\t}\n}","preventionTips":["Pin frpc and frps to the same version in deployment manifests.","Set udpPacketCodec identically in server, client, and visitor configs.","Prefer disabling the binary codec over running mixed versions."],"tags":["protocol","udp","codec","negotiation","version-mismatch","frp"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}