What causes "stream is nil" in pion/webrtc?

Check errors from the code that opens/creates the stream before calling NewWith.

stream is nil

Error message

stream is nil

What it means

Returned by ivfreader.NewWith (and internal newWith) when the io.Reader stream argument is nil. IVFReader reads IVF container frames from a stream; a nil stream cannot be read, so construction fails immediately with this sentinel error.

Source

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

// Package ivfreader implements IVF media container reader
package ivfreader

import (
	"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

View on GitHub (pinned to 8c25dc09fa)

Solutions

Check errors from the code that opens/creates the stream before calling NewWith.
Guard with `if stream == nil` and return a contextual error.
Use errors.Is(err, ivfreader.ErrNilStream-equivalent) when classifying the failure.

Example fix

// before
f, _ := os.Open(path)
r, _, err := ivfreader.NewWith(f) // f may be nil
// after
f, err := os.Open(path)
if err != nil {
    return err
}
r, _, err := ivfreader.NewWith(f)

Defensive patterns

Strategy: validation

Validate before calling

if stream == nil {
    return errors.New("IVF input stream is nil")
}
r, hdr, err := ivfreader.NewWith(stream)

Type guard

func hasStream(r io.Reader) bool { return r != nil }

Try / catch

r, hdr, err := ivfreader.NewWith(stream)
if err != nil {
    return fmt.Errorf("ivfreader init: %w", err)
}

Prevention

Always check the error from os.Open / network dial before NewWith.
Don't use a typed-nil (*os.File)(nil) as io.Reader; it passes a nil interface check differently.
Initialize streams in constructors that cannot silently return nil.

When it happens

Trigger: Calling ivfreader.NewWith(nil), or New on a path where the internal stream is nil.

Common situations: os.Open failing and its error ignored so the file handle is nil; an optional IVF input missing in config; test code constructing readers with untyped nil.

Related errors

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