{"record":{"id":"7b124fb82fb4a251","repo":"cloudflare/cloudflared","slug":"failed-to-suffix-session-id-to-datagram-it-will-b","errorCode":null,"errorMessage":"Failed to suffix session ID to datagram, it will be dropped","messagePattern":"Failed to suffix session ID to datagram, it will be dropped","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quic/datagram.go","lineNumber":53,"sourceCode":"\t\tsession:   quicSession,\n\t\tlogger:    &logger,\n\t\tdemuxChan: demuxChan,\n\t}\n}\n\n// Maximum application payload to send to / receive from QUIC datagram frame\nfunc (dm *DatagramMuxer) mtu() int {\n\treturn maxDatagramPayloadSize\n}\n\nfunc (dm *DatagramMuxer) SendToSession(session *packet.Session) error {\n\tif len(session.Payload) > dm.mtu() {\n\t\tpacketTooBigDropped.Inc()\n\t\treturn fmt.Errorf(\"origin UDP payload has %d bytes, which exceeds transport MTU %d\", len(session.Payload), dm.mtu())\n\t}\n\tpayloadWithMetadata, err := SuffixSessionID(session.ID, session.Payload)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"Failed to suffix session ID to datagram, it will be dropped\")\n\t}\n\tif err := dm.session.SendDatagram(payloadWithMetadata); err != nil {\n\t\treturn errors.Wrap(err, \"Failed to send datagram back to edge\")\n\t}\n\treturn nil\n}\n\nfunc (dm *DatagramMuxer) ServeReceive(ctx context.Context) error {\n\tfor {\n\t\t// Extracts datagram session ID, then sends the session ID and payload to receiver\n\t\t// which determines how to proxy to the origin. It assumes the datagram session has already been\n\t\t// registered with receiver through other side channel\n\t\tmsg, err := dm.session.ReceiveDatagram(ctx)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif err := dm.demux(ctx, msg); err != nil {\n\t\t\tdm.logger.Error().Err(err).Msg(\"Failed to demux datagram\")","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/quic/datagram.go#L35-L71","documentation":"In the QUIC datagram muxer (quic/datagram.go), SendToSession first rejects payloads larger than the transport MTU, then appends the session ID to the UDP payload via SuffixSessionID. If suffixing fails (session ID encoding/length problem), the datagram is dropped and this wrapped error is returned — the packet never reaches the edge.","triggerScenarios":"SuffixSessionID(session.ID, session.Payload) returns an error, i.e. appending the session ID to the payload fails (malformed/oversized session ID relative to the datagram budget).","commonSituations":"Corrupted or incorrectly decoded session ID arriving from the edge demux path; UDP payload so close to the MTU that the appended session ID cannot fit within constraints enforced by the suffix helper.","solutions":["Inspect the wrapped SuffixSessionID error to confirm whether the session ID or payload is at fault.","Reduce the origin UDP payload size so it fits the MTU with room for the session ID suffix (the explicit MTU check above this code already guards payloads > mtu).","Restart the affected UDP session to get a fresh, valid session ID if the ID appears corrupted.","Ensure both cloudflared and the edge are on compatible versions (datagram protocol mismatches can corrupt session metadata)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// enforce payload size before sending, leaving room for the session ID suffix\nconst maxUDPPayload = 1213 // stay below QUIC datagram MTU\nif len(payload) > maxUDPPayload {\n    return fmt.Errorf(\"UDP payload %d exceeds %d-byte limit\", len(payload), maxUDPPayload)\n}","typeGuard":null,"tryCatchPattern":"if err := muxer.SendToSession(datagram); err != nil {\n    if strings.Contains(err.Error(), \"suffix session ID\") {\n        // recreate session: session ID state is suspect\n        session = reopenSession(datagram.ID)\n    }\n    // UDP is best-effort: drop and continue\n}","preventionTips":["Keep origin UDP payloads comfortably below the transport MTU.","Treat tunnel UDP as lossy; add application-level retries/acknowledgement.","Keep cloudflared updated so session-ID encoding matches edge expectations.","Alert on packetTooBigDropped metric increases."],"tags":["quic","udp","datagram","packet-drop"],"backgroundTag":"payload-too-large","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}