{"record":{"id":"68f0fceaa79a03c9","repo":"pion/webrtc","slug":"w-unsupported-family-d","errorCode":null,"errorMessage":"%w: unsupported family %d","messagePattern":"%w: unsupported family (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":650,"sourceCode":"\tif err := validateFamilySpecificChannelMapping(family, streamCount, coupledCount, mapping); err != nil {\n\t\treturn channelMapping{}, err\n\t}\n\n\treturn channelMapping{\n\t\tfamily:       family,\n\t\tchannelCount: uint8(len(mapping)), //nolint:gosec // validated <= MaxUint8.\n\t\tstreamCount:  streamCount,\n\t\tcoupledCount: coupledCount,\n\t\tmapping:      append([]byte(nil), mapping...),\n\t}, nil\n}\n\nfunc validateChannelMappingFamily(family uint8) error {\n\tswitch family {\n\tcase channelMappingFamily1, channelMappingFamily2, channelMappingFamily255:\n\t\treturn nil\n\tdefault:\n\t\treturn fmt.Errorf(\"%w: unsupported family %d\", errInvalidChannelMap, family)\n\t}\n}\n\nfunc validateChannelMappingLayout(streamCount, coupledCount uint8, mapping []byte) error {\n\tif len(mapping) == 0 || len(mapping) > math.MaxUint8 {\n\t\treturn errInvalidChannelCount\n\t}\n\tif streamCount != 1 {\n\t\treturn fmt.Errorf(\"%w: stream count must be one\", errInvalidChannelMap)\n\t}\n\tif coupledCount > streamCount {\n\t\treturn fmt.Errorf(\"%w: coupled count exceeds stream count\", errInvalidChannelMap)\n\t}\n\n\tdecodedChannels := int(streamCount) + int(coupledCount)\n\tfor _, channel := range mapping {\n\t\tif channel != math.MaxUint8 && int(channel) >= decodedChannels {\n\t\t\treturn fmt.Errorf(\"%w: channel map entry is out of range\", errInvalidChannelMap)","sourceCodeStart":632,"sourceCodeEnd":668,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L632-L668","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\nerr := validateChannelMapping(0, streamCount, coupledCount, mapping) // family 0 unsupported here\n// after\nerr := validateChannelMapping(channelMappingFamily1, streamCount, coupledCount, mapping)","handlingStrategy":"validation","validationCode":"func isSupportedMappingFamily(family uint8) bool {\n    switch family {\n    case 1, 2, 255: // channelMappingFamily1, 2, 255\n        return true\n    }\n    return false\n}","typeGuard":null,"tryCatchPattern":"mapping, err := validateChannelMapping(family, streamCount, coupledCount, mappingBytes)\nif err != nil {\n    if errors.Is(err, errInvalidChannelMap) {\n        return fmt.Errorf(\"unsupported channel mapping family %d: %w\", family, err)\n    }\n    return err\n}","preventionTips":["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."],"tags":["go","ogg","opus","channel-mapping","invalid-configuration"],"backgroundTag":"unsupported-opus-channel-mapping-family","analyzedSha":"8c25dc09fa9e7c09aac4309ead88093d760432b0","analyzedAt":"2026-09-03T21:56:56.182Z","contentChangedAt":"2026-09-03T21:56:56.182Z","schemaVersion":2},"datasetVersion":"2026-09-11T07:07:21.782Z"}