{"record":{"id":"3586984a120c9c78","repo":"pion/webrtc","slug":"w-channel-map-entry-is-out-of-range","errorCode":null,"errorMessage":"%w: channel map entry is out of range","messagePattern":"%w: channel map entry is out of range","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/media/oggwriter/oggwriter.go","lineNumber":668,"sourceCode":"\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)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc validateFamilySpecificChannelMapping(\n\tfamily uint8,\n\tstreamCount uint8,\n\tcoupledCount uint8,\n\tmapping []byte,\n) error {\n\tswitch family {\n\tcase channelMappingFamily1:\n\t\treturn validateVorbisChannelMapping(streamCount, coupledCount, mapping)\n\tcase channelMappingFamily2:\n\t\tif len(mapping) != 1 || streamCount != 1 || coupledCount != 0 || mapping[0] != 0 {\n\t\t\treturn fmt.Errorf(\"%w: invalid family 2 mapping\", errInvalidChannelMap)","sourceCodeStart":650,"sourceCodeEnd":686,"githubUrl":"https://github.com/pion/webrtc/blob/8c25dc09fa9e7c09aac4309ead88093d760432b0/pkg/media/oggwriter/oggwriter.go#L650-L686","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make every non-255 mapping entry < streamCount + coupledCount; raise stream/coupled counts or fix the indexes.","Use 255 for padding/silent channels rather than fake indexes.","For mono/stereo, use the canonical mappings {0} and {0,1}.","Validate the table locally (loop over entries checking channel != 255 && int(channel) < streams+coupled) before calling the writer."],"exampleFix":"// before\nvalidateChannelMapping(family, 1, 0, []byte{0, 1}) // decodedChannels=1, index 1 out of range\n// after\nvalidateChannelMapping(family, 1, 1, []byte{0, 1}) // decodedChannels=2","handlingStrategy":"validation","validationCode":"func validMappingEntries(streams, coupled uint8, mapping []byte) bool {\n    decoded := int(streams) + int(coupled)\n    for _, c := range mapping {\n        if c != 255 && int(c) >= decoded { return false }\n    }\n    return true\n}","typeGuard":"func isMappingInRange(streams, coupled uint8, mapping []byte) bool {\n    decoded := int(streams) + int(coupled)\n    for _, c := range mapping { if c != 255 && int(c) >= decoded { return false } }\n    return true\n}","tryCatchPattern":"if err := validateChannelMapping(f, s, c, m); err != nil {\n    if errors.Is(err, errInvalidChannelMap) { /* inspect mapping entries */ }\n    return err\n}","preventionTips":["Use 255 for silent padding channels, never fake indexes","Keep every entry < streamCount+coupledCount","Copy canonical tables: {0} mono, {0,1} stereo","Recheck mapping tables when changing stream/coupled counts"],"tags":["go","ogg","opus","channel-mapping","validation"],"backgroundTag":"invalid-opus-channel-mapping","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"}