{"record":{"id":"994c9c1f386e320b","repo":"EllanJiang/GameFramework","slug":"sound-group-is-invalid","errorCode":null,"errorMessage":"Sound group is invalid.","messagePattern":"Sound group is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.SoundAgent.cs","lineNumber":38,"sourceCode":"            private readonly ISoundHelper m_SoundHelper;\n            private readonly ISoundAgentHelper m_SoundAgentHelper;\n            private int m_SerialId;\n            private object m_SoundAsset;\n            private DateTime m_SetSoundAssetTime;\n            private bool m_MuteInSoundGroup;\n            private float m_VolumeInSoundGroup;\n\n            /// <summary>\n            /// 初始化声音代理的新实例。\n            /// </summary>\n            /// <param name=\"soundGroup\">所在的声音组。</param>\n            /// <param name=\"soundHelper\">声音辅助器接口。</param>\n            /// <param name=\"soundAgentHelper\">声音代理辅助器接口。</param>\n            public SoundAgent(SoundGroup soundGroup, ISoundHelper soundHelper, ISoundAgentHelper soundAgentHelper)\n            {\n                if (soundGroup == null)\n                {\n                    throw new GameFrameworkException(\"Sound group is invalid.\");\n                }\n\n                if (soundHelper == null)\n                {\n                    throw new GameFrameworkException(\"Sound helper is invalid.\");\n                }\n\n                if (soundAgentHelper == null)\n                {\n                    throw new GameFrameworkException(\"Sound agent helper is invalid.\");\n                }\n\n                m_SoundGroup = soundGroup;\n                m_SoundHelper = soundHelper;\n                m_SoundAgentHelper = soundAgentHelper;\n                m_SoundAgentHelper.ResetSoundAgent += OnResetSoundAgent;\n                m_SerialId = 0;\n                m_SoundAsset = null;","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.SoundAgent.cs#L20-L56","documentation":"The SoundAgent constructor validates that the SoundGroup it is being attached to is not null. An agent always belongs to a sound group; a null group would break playback management and stop logic, so construction fails immediately with GameFrameworkException.","triggerScenarios":"Constructing SoundAgent(null, soundHelper, soundAgentHelper) — typically inside SoundManager.PlaySound when PlaySound is called with a null soundGroup, or custom agent creation code passing an unassigned group.","commonSituations":"PlaySound invoked with a group name that has no corresponding SoundGroup (group never created via AddSoundGroup); typo in group name; custom sound code building agents directly without a group.","solutions":["Ensure the sound group exists before playing: call soundManager.AddSoundGroup(name) and verify PlaySound uses an existing group name.","Check the error log for a preceding 'Sound group is not exist' message and fix the group name.","If constructing agents manually, obtain the group via soundManager.GetSoundGroup(name) and null-check it first."],"exampleFix":"// before\nm_SoundManager.PlaySound(4, asset, null, null); // group index invalid -> group null\n// after\nif (m_SoundManager.GetSoundGroup(\"Music\") == null) { m_SoundManager.AddSoundGroup(\"Music\"); }\nm_SoundManager.PlaySound(\"Music\", asset, null, null);","handlingStrategy":"validation","validationCode":"var group = soundManager.GetSoundGroup(groupName);\nif (group == null) { soundManager.AddSoundGroup(groupName); group = soundManager.GetSoundGroup(groupName); }","typeGuard":"bool HasSoundGroup(SoundManager m, string name) => m.GetSoundGroup(name) != null;","tryCatchPattern":"try { soundManager.PlaySound(groupName, asset); } catch (GameFrameworkException ex) when (ex.Message.Contains(\"Sound group is invalid\")) { Log.Error($\"Sound group '{groupName}' does not exist\"); }","preventionTips":["Create all sound groups at startup via AddSoundGroup","Use constants for group names","Check logs for 'Sound group is not exist' before PlaySound"],"tags":["gameframework","audio","null-argument","sound-group"],"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"}