pion/webrtc · error

%w: expected OpusHead, got %s

Error message

%w: expected OpusHead, got %s

What it means

Raised in oggreader.validateOpusPageHeader (called from readOpusHeader) when the first logical Ogg page of an Opus stream does not carry the required "OpusHead" identification-page payload signature. The wrap includes the signature actually found (possibly empty when the payload is too short to contain one). The offending input is an Ogg stream whose ID page payload is not an Opus identification header.

Source

Thrown at pkg/media/oggreader/oggreader.go:217

func validateOpusPageHeader(pageHeader *OggPageHeader, payload []byte) error {
	if string(pageHeader.sig[:]) != pageHeaderSignature {
		return errBadIDPageSignature
	}

	if pageHeader.headerType != pageHeaderTypeBeginningOfStream {
		return errBadIDPageType
	}

	if len(payload) < idPageBasePayloadLength {
		return errBadIDPageLength
	}

	if sig, ok := opusPayloadSignature(payload); !ok || sig != HeaderOpusID {
		return fmt.Errorf("%w: expected OpusHead, got %s", errBadIDPagePayloadSignature, sig)
	}

	return nil
}

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Verify the input is an Opus-in-Ogg stream, not another codec (e.g. Vorbis) or arbitrary data
2. Check the stream starts at the beginning; joining mid-stream skips the OpusHead ID page
3. Re-mux the file with ffmpeg (ffmpeg -i in.ogg -c copy fixed.ogg) to regenerate headers
4. Log the wrapped signature to diagnose what codec the page actually contains

When it happens

Trigger: Thrown at pkg/media/oggreader/oggreader.go:217 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/929536cce62226c4. Report an issue: GitHub.