pion/webrtc · error

invalid OpusTags

Error message

invalid OpusTags

What it means

errInvalidOpusTags is a sentinel wrapped by fmt.Errorf in the OpusTags validation used when writing the Opus comment header page. It fires when the caller-supplied OpusTags structure cannot be serialized: more user comments than fit a uint32 count, or the resulting comment header exceeds the maximum allowed header length (vendor string plus each COMMENT entry is length-checked).

Source

Thrown at pkg/media/oggwriter/oggwriter.go:58

func validateOpusTagsWithMaxHeaderLen(opusTags OpusTags, maxHeaderLen uint64) error {
	if err := validateOpusTagString("vendor", opusTags.Vendor); err != nil {
		return err
	}
	if uint64(len(opusTags.UserComments)) > maxUint32Length {
		return fmt.Errorf("%w: too many user comments", errInvalidOpusTags)
	}

	if err := validateUserComments(opusTags.UserComments); err != nil {
		return err
	}

	return validateOpusTagsHeaderLen(opusTags, maxHeaderLen)
}

func validateOpusTagsHeaderLen(opusTags OpusTags, maxHeaderLen uint64) error {
	headerLen := uint64(len(commentPageSignature)) + 4 + uint64(len(opusTags.Vendor)) + 4
	if headerLen > maxHeaderLen {
		return fmt.Errorf("%w: header is too long", errInvalidOpusTags)
	}

	for _, comment := range opusTags.UserComments {
		userCommentLen := uint64(len(comment.Comment)) + 1 + uint64(len(comment.Value))
		commentFieldLen := 4 + userCommentLen
		if commentFieldLen > maxHeaderLen-headerLen {
			return fmt.Errorf("%w: header is too long", errInvalidOpusTags)
		}
		headerLen += commentFieldLen
	}

	return nil
}

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Reduce the number of user comments so the count fits in uint32
2. Shorten the vendor string or comment values so the total header fits the maximum size
3. Drop optional comments before writing; keep only essential tags
4. Validate OpusTags with the same limits before constructing the writer input

When it happens

Trigger: Thrown at pkg/media/oggwriter/oggwriter.go:58 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pion/webrtc@8c25dc09fa (2026-09-03). Data as JSON: /api/errors/081d54760d9bab68. Report an issue: GitHub.