pion/webrtc · error

invalid nil packet

Error message

invalid nil packet

What it means

errInvalidNilPacket is returned when a nil RTP packet is passed to a writer's WriteRTP-style method. Writers cannot serialize a nil packet, so they reject it up front. The same sentinel exists in both oggwriter and ivfwriter, and tests use it as the expected error for empty/nil packets.

Source

Thrown at pkg/media/oggwriter/oggwriter.go:50

	defaultChannelCount                = 2
	channelMappingFamily0              = 0
	channelMappingFamily1              = 1
	channelMappingFamily2              = 2
	channelMappingFamily255            = 255
	idPageSignature                    = "OpusHead"
	commentPageSignature               = "OpusTags"
	defaultVendor                      = "pion"
	pageHeaderSignature                = "OggS"
	pageHeaderSize                     = 27
	maxOggPageSegments                 = 255
	noGranulePosition                  = ^uint64(0)
	maxUint32Length                    = uint64(1<<32 - 1)
)

var (
	errFileNotOpened        = errors.New("file not opened")
	errOutputNotOpened      = errors.New("output not opened")
	errInvalidNilPacket     = errors.New("invalid nil packet")
	errDuplicateTrackSSRC   = errors.New("duplicate Ogg track SSRC")
	errDuplicateTrackSerial = errors.New("duplicate Ogg track serial")
	errTracksStarted        = errors.New("cannot add Ogg tracks after writing has started")
	errPacketSSRCMismatch   = errors.New("RTP packet SSRC does not match Ogg track SSRC")
	errInvalidOpusPacket    = errors.New("invalid Opus packet")
	errInvalidChannelCount  = errors.New("invalid channel count")
	errInvalidChannelMap    = errors.New("invalid channel mapping")
	errInvalidOpusTags      = errors.New("invalid OpusTags")
)

type pageRewriter interface {
	io.Seeker
	io.WriterAt
}

type writerConfig struct {
	sampleRate     uint32
	channelMapping channelMapping

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Skip nil packets before calling WriteRTP
2. Ensure the RTP packet is fully populated (header and payload) before writing
3. Fix upstream producers that emit nil packets on error paths

Example fix

// before
writer.WriteRTP(pkt) // pkt may be nil
// after
if pkt == nil || pkt.Payload == nil {
    return nil // or log and skip
}
writer.WriteRTP(pkt)

if pkt == nil || pkt.Header == nil {
    return errors.New("cannot write nil RTP packet")
}
err := writer.WriteRTP(pkt)

func isWritablePacket(pkt *rtp.Packet) bool {
    return pkt != nil && pkt.Payload != nil
}

if err := writer.WriteRTP(pkt); err != nil {
    if errors.Is(err, oggwriter.ErrInvalidNilPacket) {
        // skip and continue; do not treat as fatal
        return nil
    }
    return err
}

When it happens

Trigger: Calling WriteRTP(nil) on an Ogg/IVF writer; passing &rtp.Packet{} that the writer treats as invalid (ivfwriter_test.go:42 expects errInvalidNilPacket for an empty packet).

Common situations: A packet-producing loop forwards a nil packet after an upstream error, a channel of packets is closed and nil drained, track pipelines that emit placeholder packets.

Related errors

• file not opened
• stream is nil
• payload for id page must be 19 bytes
• output not opened
• duplicate Ogg track SSRC

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