{"record":{"id":"df5a0c1397e5148c","repo":"EllanJiang/GameFramework","slug":"sound-group-helper-is-invalid","errorCode":null,"errorMessage":"Sound group helper is invalid.","messagePattern":"Sound group helper is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.SoundGroup.cs","lineNumber":40,"sourceCode":"            private bool m_AvoidBeingReplacedBySamePriority;\n            private bool m_Mute;\n            private float m_Volume;\n\n            /// <summary>\n            /// 初始化声音组的新实例。\n            /// </summary>\n            /// <param name=\"name\">声音组名称。</param>\n            /// <param name=\"soundGroupHelper\">声音组辅助器。</param>\n            public SoundGroup(string name, ISoundGroupHelper soundGroupHelper)\n            {\n                if (string.IsNullOrEmpty(name))\n                {\n                    throw new GameFrameworkException(\"Sound group name is invalid.\");\n                }\n\n                if (soundGroupHelper == null)\n                {\n                    throw new GameFrameworkException(\"Sound group helper is invalid.\");\n                }\n\n                m_Name = name;\n                m_SoundGroupHelper = soundGroupHelper;\n                m_SoundAgents = new List<SoundAgent>();\n            }\n\n            /// <summary>\n            /// 获取声音组名称。\n            /// </summary>\n            public string Name\n            {\n                get\n                {\n                    return m_Name;\n                }\n            }\n","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.SoundGroup.cs#L22-L58","documentation":"Thrown by the SoundGroup constructor when the soundGroupHelper argument is null. A sound group needs an ISoundGroupHelper to function (e.g. for priority/avoid-replacement behavior), so GameFramework rejects null helpers at construction time.","triggerScenarios":"new SoundGroup(name, null); passing a helper field that was never assigned; failing to create/obtain the concrete SoundGroupHelper before building groups.","commonSituations":"Forgetting to add the SoundHelper/SoundGroupHelper component to the Unity Sound component; initialization order issues where the helper is created after groups; a factory returning null.","solutions":["Create or obtain a valid ISoundGroupHelper and pass it to the constructor","Ensure the helper component is attached/initialized before adding sound groups","Null-check the helper at the call site before constructing the group"],"exampleFix":"// before\nvar group = new SoundGroup(\"Music\", null);\n// after\nISoundGroupHelper helper = GetComponent<SoundGroupHelper>();\nvar group = new SoundGroup(\"Music\", helper);","handlingStrategy":"type-guard","validationCode":"if (soundGroupHelper == null) throw new ArgumentNullException(nameof(soundGroupHelper));\nvar group = new SoundGroup(name, soundGroupHelper);","typeGuard":"bool HasHelper(ISoundGroupHelper h) => h != null;","tryCatchPattern":"try { var group = new SoundGroup(name, helper); }\ncatch (GameFrameworkException ex) { Log.Error(ex.Message); }","preventionTips":["Attach SoundGroupHelper components before creating groups","Check GetComponent results for null before use","Initialize helpers in Awake, groups in Start"],"tags":["gameframework","sound","null-argument"],"backgroundTag":"null-argument","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}