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

Check that the io.Reader is non-nil before calling NewReader and handle the upstream failure that produced nil.

stream is nil

Error message

stream is nil

What it means

This error is returned by h264reader.NewReader when the io.Reader passed in is nil. The H264Reader wraps a reader to parse an H264 Annex-B bitstream; without a source stream there is nothing to read. It is a package-level sentinel (errNilReader) so callers can compare with errors.Is.

Source

Thrown at pkg/media/h264reader/h264reader.go:25

import (
	"bytes"
	"errors"
	"io"
)

// H264Reader reads data from stream and constructs h264 nal units.
type H264Reader struct {
	stream                      io.Reader
	nalBuffer                   []byte
	countOfConsecutiveZeroBytes int
	nalPrefixParsed             bool
	readBuffer                  []byte
	tmpReadBuf                  []byte
	includeSEI                  bool
}

var (
	errNilReader           = errors.New("stream is nil")
	errDataIsNotH264Stream = errors.New("data is not a H264 bitstream")
)

// NewReader creates new H264Reader.
func NewReader(in io.Reader) (*H264Reader, error) {
	if in == nil {
		return nil, errNilReader
	}

	reader := &H264Reader{
		stream:          in,
		nalBuffer:       make([]byte, 0),
		nalPrefixParsed: false,
		readBuffer:      make([]byte, 0),
		tmpReadBuf:      make([]byte, 4096),
		includeSEI:      false,
	}

View on GitHub (pinned to 8c25dc09fa)

Solutions

Check that the io.Reader is non-nil before calling NewReader and handle the upstream failure that produced nil.
Compare the returned error with errors.Is(err, h264reader.ErrNilReader-style check) / direct equality to give a clear message.
Return a descriptive error to your caller instead of propagating the bare sentinel.

Example fix

// before
rdr, err := h264reader.NewReader(getReader())
// after
in := getReader()
if in == nil {
    return nil, fmt.Errorf("no H264 input stream available")
}
rdr, err := h264reader.NewReader(in)

Defensive patterns

Strategy: validation

Validate before calling

if in == nil {
    return errors.New("h264 input stream is nil")
}
rdr, err := h264reader.NewReader(in)

Type guard

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

Try / catch

rdr, err := h264reader.NewReader(in)
if err != nil {
    return fmt.Errorf("h264reader init: %w", err)
}

Prevention

Always check errors from whatever creates the io.Reader before passing it on.
Avoid functions that return a bare nil io.Reader with a nil error.
Validate inputs at API boundaries before constructing media readers.

When it happens

Trigger: Calling h264reader.NewReader(nil), typically when a variable holding the stream is nil because an earlier open/lookup step failed silently.

Common situations: Config mistakes where a file path or network source was never opened; a function that returns an io.Reader returning nil on a code path; forgetting to check a producer's error before passing its (nil) result to NewReader.

Related errors

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