pion/webrtc · error

expected and actual checksum do not match

Error message

expected and actual checksum do not match

What it means

errChecksumMismatch is returned by ParseNextPage when the CRC32 checksum computed over the Ogg page does not match the checksum stored in the page header (bytes 22-25, little-endian). Ogg pages carry a CRC to detect corruption, and this library validates it.

Source

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

)

const (
	pageHeaderTypeBeginningOfStream = 0x02
	pageHeaderSignature             = "OggS"

	idPageBasePayloadLength = 19
	pageHeaderLen           = 27
)

var (
	errNilStream                       = errors.New("stream is nil")
	errBadIDPageSignature              = errors.New("bad header signature")
	errBadOpusTagsSignature            = errors.New("bad opus tags signature")
	errBadIDPageType                   = errors.New("wrong header, expected beginning of stream")
	errBadIDPageLength                 = errors.New("payload for id page must be 19 bytes")
	errBadIDPagePayloadSignature       = errors.New("bad payload signature")
	errShortPageHeader                 = errors.New("not enough data for payload header")
	errChecksumMismatch                = errors.New("expected and actual checksum do not match")
	errUnsupportedChannelMappingFamily = errors.New("unsupported channel mapping family")
)

// OggReader is used to read Ogg files and return page payloads.
type OggReader struct {
	stream               io.Reader
	bytesReadSuccesfully int64
	checksumTable        *[256]uint32
	doChecksum           bool
}

// OggHeader contains Opus codec metadata parsed from an Opus ID page.
// This header is extracted from an Ogg page payload that starts with the OpusHead
// signature (the first page of an Opus stream in an Ogg container).
//
// Use OggPageHeader.OpusPacketType() to classify a page payload as OpusHead,
// and OggPageHeader.ParseOpusHeader() to parse the OpusHead payload.
//

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Re-obtain the file/stream; verify integrity (checksum the download)
2. If you generate Ogg pages, compute the standard Ogg CRC32 (poly 0x04c11db7, init 0) over the full page with the checksum field zeroed
3. Check any code that mutates page bytes in place

Example fix

// before: writer leaves stale checksum after payload edit
payload[5] = 0x01
// after: recompute page CRC with zeroed field
binary.LittleEndian.PutUint32(header[22:26], 0)
crc := oggCRC(append(header, payload...))
binary.LittleEndian.PutUint32(header[22:26], crc)

page, payload, err := reader.ParseNextPage()
if errors.Is(err, oggreader.ErrChecksumMismatch) {
    // page corrupted: log page offset, resync or re-fetch source
}

When it happens

Trigger: ParseNextPage (oggreader.go:334) computes the page checksum and compares it to binary.LittleEndian.Uint32(header[22:26]); any bit corruption or wrong checksum field triggers it. Also asserted directly in tests.

Common situations: File corrupted on disk or during transfer, buggy custom page writer that fails to compute the Ogg CRC, byte-level edits to page payloads without recomputing checksums.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• stream is nil
• bad header signature
• bad opus tags signature
• wrong header, expected beginning of stream
• payload for id page must be 19 bytes

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