pion/webrtc · error
%w: unsupported family %d
Error message
%w: unsupported family %d
What it means
Returned by validateChannelMappingFamily when an Ogg Opus channel mapping family value is not one of the supported values (the library's channelMappingFamily1, 2, or 255 constants). The Opus spec defines families 0 and 1; this library accepts only its configured set, so any other family byte is rejected with errInvalidChannelMap.
Source
Thrown at pkg/media/oggwriter/oggwriter.go:650
if err := validateFamilySpecificChannelMapping(family, streamCount, coupledCount, mapping); err != nil {
return channelMapping{}, err
}
return channelMapping{
family: family,
channelCount: uint8(len(mapping)), //nolint:gosec // validated <= MaxUint8.
streamCount: streamCount,
coupledCount: coupledCount,
mapping: append([]byte(nil), mapping...),
}, nil
}
func validateChannelMappingFamily(family uint8) error {
switch family {
case channelMappingFamily1, channelMappingFamily2, channelMappingFamily255:
return nil
default:
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)View on GitHub (pinned to 8c25dc09fa)
Solutions
- Use one of the library's supported family constants (channelMappingFamily1, channelMappingFamily2, or channelMappingFamily255).
- For plain mono/stereo, don't set a custom channel mapping — use the default mapping (family 0 handled internally).
- Map your source channel family to a supported one, or remap channels before writing.
- Check the library version/docs for which families are supported, as the accepted set may differ from the raw Opus spec.
Example fix
// before err := validateChannelMapping(0, streamCount, coupledCount, mapping) // family 0 unsupported here // after err := validateChannelMapping(channelMappingFamily1, streamCount, coupledCount, mapping)
Defensive patterns
Strategy: validation
Validate before calling
func isSupportedMappingFamily(family uint8) bool {
switch family {
case 1, 2, 255: // channelMappingFamily1, 2, 255
return true
}
return false
} Try / catch
mapping, err := validateChannelMapping(family, streamCount, coupledCount, mappingBytes)
if err != nil {
if errors.Is(err, errInvalidChannelMap) {
return fmt.Errorf("unsupported channel mapping family %d: %w", family, err)
}
return err
} Prevention
- Only use the family constants exported by the library; don't pass raw bytes from headers.
- For mono/stereo, rely on the default channel mapping instead of configuring one manually.
- Consult the library docs for the supported family set before adding multichannel support.
- Add a unit test that asserts configured family values against the accepted set.
When it happens
Trigger: Passing a family value outside {1, 2, 255} to the channel-mapping configuration path (validateChannelMapping) when setting up an Ogg Opus writer — e.g. family 0, 3, or an arbitrary byte read from a header.
Common situations: Configuring surround/multichannel output with an unsupported family constant, copying a family byte from another file without mapping it to a supported value, or typos in channel-configuration code (using 0 where the library expects 1).
Related errors
- %w: stream count must be one
- %w: coupled count exceeds stream count
- %w: channel map entry is out of range
- %w: invalid family 2 mapping
- %w: unsupported family 1 channel count
AI-assisted analysis of pion/webrtc@8c25dc09fa (2026-09-03).
Data as JSON: /api/errors/68f0fceaa79a03c9.
Report an issue: GitHub.