pion/webrtc · error

%w: channel map entry is out of range

Error message

%w: channel map entry is out of range

What it means

Each entry in the channel mapping array is an output channel index; indexes must be either 255 (a silent/denorm channel) or less than decodedChannels = streamCount + coupledCount. This error is returned when a mapping entry points at a non-existent stream, which would make the decoded output ambiguous. It wraps errInvalidChannelMap.

Source

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

		return fmt.Errorf("%w: unsupported family %d", errInvalidChannelMap, family)
	}
}

func validateChannelMappingLayout(streamCount, coupledCount uint8, mapping []byte) error {
	if len(mapping) == 0 || len(mapping) > math.MaxUint8 {
		return errInvalidChannelCount
	}
	if streamCount != 1 {
		return fmt.Errorf("%w: stream count must be one", errInvalidChannelMap)
	}
	if coupledCount > streamCount {
		return fmt.Errorf("%w: coupled count exceeds stream count", errInvalidChannelMap)
	}

	decodedChannels := int(streamCount) + int(coupledCount)
	for _, channel := range mapping {
		if channel != math.MaxUint8 && int(channel) >= decodedChannels {
			return fmt.Errorf("%w: channel map entry is out of range", errInvalidChannelMap)
		}
	}

	return nil
}

func validateFamilySpecificChannelMapping(
	family uint8,
	streamCount uint8,
	coupledCount uint8,
	mapping []byte,
) error {
	switch family {
	case channelMappingFamily1:
		return validateVorbisChannelMapping(streamCount, coupledCount, mapping)
	case channelMappingFamily2:
		if len(mapping) != 1 || streamCount != 1 || coupledCount != 0 || mapping[0] != 0 {
			return fmt.Errorf("%w: invalid family 2 mapping", errInvalidChannelMap)

View on GitHub (pinned to 8c25dc09fa)

Solutions

1. Make every non-255 mapping entry < streamCount + coupledCount; raise stream/coupled counts or fix the indexes.
2. Use 255 for padding/silent channels rather than fake indexes.
3. For mono/stereo, use the canonical mappings {0} and {0,1}.
4. Validate the table locally (loop over entries checking channel != 255 && int(channel) < streams+coupled) before calling the writer.

Example fix

// before
validateChannelMapping(family, 1, 0, []byte{0, 1}) // decodedChannels=1, index 1 out of range
// after
validateChannelMapping(family, 1, 1, []byte{0, 1}) // decodedChannels=2

func validMappingEntries(streams, coupled uint8, mapping []byte) bool {
    decoded := int(streams) + int(coupled)
    for _, c := range mapping {
        if c != 255 && int(c) >= decoded { return false }
    }
    return true
}

func isMappingInRange(streams, coupled uint8, mapping []byte) bool {
    decoded := int(streams) + int(coupled)
    for _, c := range mapping { if c != 255 && int(c) >= decoded { return false } }
    return true
}

if err := validateChannelMapping(f, s, c, m); err != nil {
    if errors.Is(err, errInvalidChannelMap) { /* inspect mapping entries */ }
    return err
}

When it happens

Trigger: Supplying a mapping like []byte{0, 2} with streamCount=1, coupledCount=0 (decodedChannels=1), so index 2 >= 1; any custom mapping table with out-of-range indexes passed when configuring a track.

Common situations: Hand-written mapping tables copied from larger channel layouts (e.g. 6-channel tables) while declaring only 1-2 streams; mappings intended for a different stream configuration than the one declared.

Related errors

• %w: stream count must be one
• %w: coupled count exceeds stream count
• %w: invalid family 2 mapping
• %w: unsupported family 1 channel count
• %w: invalid family 1 mapping

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