pion/webrtc · error
%w: user comment is too long
Error message
%w: user comment is too long
What it means
This error is returned by validateUserComment when a single OpusTags user comment (NAME=value) cannot be represented in the Ogg OpusTags header because its total encoded length — comment name length + 1 separator byte + value length — exceeds maxUint32Length (0xFFFFFFFF). The OpusComments spec stores each comment with a 32-bit little-endian length prefix, so a combined size larger than a uint32 cannot be serialized. It is wrapped by errInvalidOpusTags, which the caller can check with errors.Is.
Source
Thrown at pkg/media/oggwriter/oggwriter.go:814
func validateUserComments(comments []UserComment) error {
for _, comment := range comments {
if err := validateUserComment(comment); err != nil {
return err
}
}
return nil
}
func validateUserComment(comment UserComment) error {
if !isValidCommentName(comment.Comment) {
return fmt.Errorf("%w: invalid user comment name", errInvalidOpusTags)
}
if err := validateOpusTagString("user comment value", comment.Value); err != nil {
return err
}
if uint64(len(comment.Comment))+1+uint64(len(comment.Value)) > maxUint32Length {
return fmt.Errorf("%w: user comment is too long", errInvalidOpusTags)
}
return nil
}
func validateOpusTagString(field, value string) error {
if !utf8.ValidString(value) {
return fmt.Errorf("%w: %s is not valid UTF-8", errInvalidOpusTags, field)
}
if uint64(len(value)) > maxUint32Length {
return fmt.Errorf("%w: %s is too long", errInvalidOpusTags, field)
}
return nil
}
func isValidCommentName(comment string) bool {
if comment == "" {View on GitHub (pinned to 8c25dc09fa)
Solutions
- Shorten the comment name or value so that len(name)+1+len(value) <= 4294967295 bytes (in Go, byte length of the strings).
- Move large payloads (cover art, lyrics blobs) out of OpusTags metadata into a separate sidecar file or stream.
- Add a pre-flight check on UserComment sizes before constructing the OpusTags struct to fail early with a clearer message.
- If errors.Is(err, errInvalidOpusTags) matches, log which comment is oversized; the error does not name it.
Example fix
// before
tags := oggwriter.OpusTags{UserComments: []oggwriter.UserComment{
{Comment: "COVERART", Value: string(hugeBase64Blob)}, // > 4 GiB
}}
// after
if len("COVERART")+1+len(hugeBase64Blob) > math.MaxUint32 {
return errors.New("cover art too large for OpusTags; write sidecar file instead")
}
tags := oggwriter.OpusTags{UserComments: []oggwriter.UserComment{
{Comment: "COVERART_FILE", Value: "cover.jpg"},
}} Defensive patterns
Strategy: validation
Validate before calling
func validateCommentSize(name, value string) error {
if uint64(len(name))+1+uint64(len(value)) > math.MaxUint32 {
return fmt.Errorf("user comment %q too long: %d bytes", name, len(name)+1+len(value))
}
return nil
} Try / catch
if err := writer.WriteOpusTags(tags); err != nil {
if errors.Is(err, oggwriter.ErrInvalidOpusTags) {
// trim or drop oversized comments, then retry
}
return err
} Prevention
- Cap comment name and value lengths at application level (e.g. 4 KiB) well below the uint32 limit.
- Never embed large blobs (cover art, binary) in OpusTags comments; reference them by path or URL.
- Validate all UserComment entries in a loop before handing OpusTags to the writer.
When it happens
Trigger: Calling any API that validates OpusTags (e.g. OpusTags validation via validateOpusTags / oggwriter paths that serialize the comment header) with a UserComment whose len(comment.Comment)+1+len(comment.Value) > 4294967295 bytes. In practice this requires a comment name or value of multiple gigabytes.
Common situations: Programmatically generating enormous metadata (e.g. embedding a huge base64 blob, cover art data, or a giant JSON payload as a comment value) instead of referencing it externally; unit tests pushing boundary sizes; a bug concatenating values repeatedly into one comment.
Related errors
- %w: %s is too long
- %w: invalid comment %d
- %w: stream count must be one
- %w: coupled count exceeds stream count
- %w: channel map entry is out of range
AI-assisted analysis of pion/webrtc@8c25dc09fa (2026-09-03).
Data as JSON: /api/errors/51141b71aee6d881.
Report an issue: GitHub.