{"record":{"id":"5eba9d01cb8edf6b","repo":"cloudflare/cloudflared","slug":"payload-length-is-too-large-to-be-bundled-in-datag","errorCode":null,"errorMessage":"payload length is too large to be bundled in datagram","messagePattern":"payload length is too large to be bundled in datagram","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quic/v3/datagram_errors.go","lineNumber":11,"sourceCode":"package v3\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n)\n\nvar (\n\tErrInvalidDatagramType                 error = errors.New(\"invalid datagram type expected\")\n\tErrDatagramHeaderTooSmall              error = fmt.Errorf(\"datagram should have at least %d byte\", datagramTypeLen)\n\tErrDatagramPayloadTooLarge             error = errors.New(\"payload length is too large to be bundled in datagram\")\n\tErrDatagramPayloadHeaderTooSmall       error = errors.New(\"payload length is too small to fit the datagram header\")\n\tErrDatagramPayloadInvalidSize          error = errors.New(\"datagram provided is an invalid size\")\n\tErrDatagramResponseMsgInvalidSize      error = errors.New(\"datagram response message is an invalid size\")\n\tErrDatagramResponseInvalidSize         error = errors.New(\"datagram response is an invalid size\")\n\tErrDatagramResponseMsgTooLargeMaximum  error = fmt.Errorf(\"datagram response error message length exceeds the length of the datagram maximum: %d\", maxResponseErrorMessageLen)\n\tErrDatagramResponseMsgTooLargeDatagram error = fmt.Errorf(\"datagram response error message length exceeds the length of the provided datagram\")\n\tErrDatagramICMPPayloadTooLarge         error = fmt.Errorf(\"datagram icmp payload exceeds %d bytes\", maxICMPPayloadLen)\n\tErrDatagramICMPPayloadMissing          error = errors.New(\"datagram icmp payload is missing\")\n)\n\nfunc wrapMarshalErr(err error) error {\n\treturn fmt.Errorf(\"datagram marshal error: %w\", err)\n}\n\nfunc wrapUnmarshalErr(err error) error {\n\treturn fmt.Errorf(\"datagram unmarshal error: %w\", err)\n}\n","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/quic/v3/datagram_errors.go#L1-L29","documentation":"ErrDatagramPayloadTooLarge is returned when marshaling a datagram whose payload exceeds the maximum allowed size for the datagram's destination IP family. The library enforces a hard payload limit (maxPayloadLen) because QUIC datagrams must fit within a single QUIC packet and MTU constraints. MarshalBinary checks the payload length before allocating the buffer and fails fast with this sentinel error (wrapped by wrapMarshalErr).","triggerScenarios":"Calling UDPSessionPayloadDatagram.MarshalBinary() with a Payload slice longer than maxPayloadLen (the size budget for the destination IP family). Typically happens when the caller passes an application UDP payload larger than the QUIC datagram frame can carry.","commonSituations":"Proxying an oversized UDP packet received from the origin (e.g. DNS responses over 1232 bytes, large UDP-based protocols like some QUIC/TFTP traffic); misconfigured MTU assumptions; using an IPv4-family size budget while actually sending over IPv6 or vice versa.","solutions":["Check the payload length against the library's maxPayloadLen budget before constructing the datagram and reject or truncate oversized payloads upstream","Return an ICMP 'packet too big' style response to the origin so it lowers its path MTU and retransmits a smaller packet","Keep per-protocol payload caps aligned with QUIC/UDP MTU guidance (e.g. ~1200-1500 bytes minus datagram header overhead)","Use errors.Is(err, v3.ErrDatagramPayloadTooLarge) to branch and drop/log the datagram instead of tearing down the session"],"exampleFix":"// before\npayload := make([]byte, 2000) // exceeds maxPayloadLen\ndatagram := &v3.UDPSessionPayloadDatagram{RequestID: id, Payload: payload}\n_, err := datagram.MarshalBinary() // -> ErrDatagramPayloadTooLarge\n// after\nconst maxUDPPayload = 1280 // safe budget for datagram framing\nif len(payload) > maxUDPPayload {\n    // respond ICMP type 3 code 4 'fragmentation needed' or drop\n    return\n}\ndatagram := &v3.UDPSessionPayloadDatagram{RequestID: id, Payload: payload}\n_, err := datagram.MarshalBinary()","handlingStrategy":"validation","validationCode":"if len(payload) > maxUDPPayloadLen { // query from library or use a safe MTU-derived budget\n    // drop or emit ICMP fragmentation-needed\n    return\n}","typeGuard":null,"tryCatchPattern":"if _, err := d.MarshalBinary(); errors.Is(err, v3.ErrDatagramPayloadTooLarge) {\n    logger.Warn().Int(\"len\", len(d.Payload)).Msg(\"datagram payload too large, dropped\")\n    return\n}","preventionTips":["Cap proxied UDP payloads at the QUIC datagram budget before constructing datagrams","Emit ICMP 'fragmentation needed' so origins shrink packets instead of relying on drops","Keep IPv4/IPv6 destination size budgets correct"],"tags":["quic","datagram","payload-size","network"],"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"}