pion/webrtc · error
%w: invalid user comment name
Error message
%w: invalid user comment name
What it means
Opus comment names must be printable ASCII (0x20-0x7D) excluding '=' and non-empty, per the Ogg Opus comment header spec. validateUserComment returns this wrapped errInvalidOpusTags when isValidCommentName rejects the comment's name (the part before '=').
Source
Thrown at pkg/media/oggwriter/oggwriter.go:808
headerLen += commentFieldLen
}
return nil
}
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)
}View on GitHub (pinned to 8c25dc09fa)
Solutions
- Use ASCII printable names without '=', 0x20-0x7D only, non-empty (e.g. TITLE, ARTIST, DESCRIPTION).
- Split 'NAME=value' strings into the Comment (name) and Value fields instead of embedding '=' in the name.
- Uppercase and sanitize the name (strip control/non-ASCII bytes) before adding the comment.
- Validate locally: name != "" and each byte b in 0x20..0x7D and b != '='.
Example fix
// before
UserComment{Comment: "TITLE=Song", Value: "x"} // '=' inside name
// after
UserComment{Comment: "TITLE", Value: "Song"} Defensive patterns
Strategy: validation
Validate before calling
func validCommentName(name string) bool {
if name == "" { return false }
for i := 0; i < len(name); i++ {
b := name[i]
if b < 0x20 || b > 0x7d || b == '=' { return false }
}
return true
} Type guard
func isASCIICommentName(s string) bool {
if s == "" { return false }
for i := 0; i < len(s); i++ { b := s[i]; if b < 0x20 || b > 0x7d || b == '=' { return false } }
return true
} Try / catch
if err := writer.SetOpusTags(tags); err != nil {
if errors.Is(err, errInvalidOpusTags) && strings.Contains(err.Error(), "invalid user comment name") {
// sanitize or drop offending comment
}
return err
} Prevention
- Use standard uppercase ASCII tag names (TITLE, ARTIST, ...)
- Never put '=' in the name; split NAME=value properly
- Reject/sanitize control and non-ASCII bytes in names
- Validate comments at construction time, not at write time
When it happens
Trigger: Creating a UserComment with an empty Comment field, a name containing '=', a control character (<0x20), or a byte >= 0x7E (including non-ASCII UTF-8 names like 'TITELÄ' or emoji names) and passing it through applyUserComments / the tags validation path.
Common situations: Localizing tag names to non-ASCII languages; accidentally including the full 'NAME=value' string in the Comment field so the '=' lands in the name; names built from untrusted or machine-generated input containing tabs/newlines.
Related errors
- %w: too many user comments
- %w: header is too long
- %w: user comment is too long
- %w: %s is too long
- %w: invalid comment %d
AI-assisted analysis of pion/webrtc@8c25dc09fa (2026-09-03).
Data as JSON: /api/errors/644d7b489689a51c.
Report an issue: GitHub.