IVF version unknown, parser may not parse correctly

Error message

IVF version unknown, parser may not parse correctly

What it means

Returned by parseFileHeader (wrapped with fmt.Errorf %w plus expected/got values) when the IVF header signature is valid but the version field is not 0, the only version this parser understands. Parsing may not work correctly for unknown versions.

Source

Thrown at pkg/media/ivfreader/ivfreader.go:26

	"encoding/binary"
	"errors"
	"fmt"
	"io"
)

const (
	ivfFileHeaderSignature = "DKIF"
	ivfFileHeaderSize      = 32
	ivfFrameHeaderSize     = 12
)

var (
	errNilStream             = errors.New("stream is nil")
	errIncompleteFrameHeader = errors.New("incomplete frame header")
	errIncompleteFrameData   = errors.New("incomplete frame data")
	errIncompleteFileHeader  = errors.New("incomplete file header")
	errSignatureMismatch     = errors.New("IVF signature mismatch")
	errUnknownIVFVersion     = errors.New("IVF version unknown, parser may not parse correctly")
	errInvalidMediaTimebase  = errors.New("invalid media timebase")
)

// IVFFileHeader 32-byte header for IVF files
// https://wiki.multimedia.cx/index.php/IVF
type IVFFileHeader struct {
	signature           string // 0-3
	version             uint16 // 4-5
	headerSize          uint16 // 6-7
	FourCC              string // 8-11
	Width               uint16 // 12-13
	Height              uint16 // 14-15
	TimebaseDenominator uint32 // 16-19
	TimebaseNumerator   uint32 // 20-23
	NumFrames           uint32 // 24-27
	unused              uint32 // 28-31
}

View on GitHub (pinned to 8c25dc09fa)

Solutions

Inspect the reported version in the error message; if the file is nonstandard, re-mux it with a standard tool (ffmpeg -c copy) to produce version-0 IVF.
Use errors.Is so the wrapped sentinel matches, and decide whether to proceed at your own risk or reject the file.
Check the producing encoder's output settings for a version/profile flag.

Example fix

// before
if err != nil { return err }
// after
if err != nil {
    if errors.Is(err, ivfErrUnknownIVFVersion) {
        log.Warn("nonzero IVF version, attempting best-effort parse")
    } else {
        return err
    }
}

Defensive patterns

Strategy: type-guard

Validate before calling

hdrBytes := make([]byte, 32)
io.ReadFull(f, hdrBytes)
version := binary.LittleEndian.Uint16(hdrBytes[4:6])
if version != 0 {
    log.Warnf("IVF version %d is nonstandard; parser may misbehave", version)
}
f.Seek(0, io.SeekStart)

Type guard

func isKnownIVFVersion(v uint16) bool { return v == 0 }

Try / catch

if err != nil && errors.Is(err, ivfErrUnknownIVFVersion) {
    log.Warn("nonstandard IVF version; continuing best-effort")
} else if err != nil {
    return err
}

Prevention

Prefer errors.Is over equality since this error is wrapped with fmt.Errorf %w.
Log the embedded expected/got version details when triaging producer issues.
Re-mux nonstandard files with a standard muxer to produce version-0 IVF.

When it happens

Trigger: parseFileHeader encounters header.version != 0 after a successful DKIF signature check; the error text includes the actual version number.

Common situations: IVF files produced by newer or nonstandard encoders/muxers setting a nonzero version field; corrupted version bytes; hand-crafted or fuzzed headers.

Related errors

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