EllanJiang/GameFramework · error · GameFrameworkException

Sound group is invalid.

Error message

Sound group is invalid.

What it means

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.

Solutions

1. Ensure the sound group exists before playing: call soundManager.AddSoundGroup(name) and verify PlaySound uses an existing group name.
2. Check the error log for a preceding 'Sound group is not exist' message and fix the group name.
3. If constructing agents manually, obtain the group via soundManager.GetSoundGroup(name) and null-check it first.

Example fix

// before
m_SoundManager.PlaySound(4, asset, null, null); // group index invalid -> group null
// after
if (m_SoundManager.GetSoundGroup("Music") == null) { m_SoundManager.AddSoundGroup("Music"); }
m_SoundManager.PlaySound("Music", asset, null, null);

var group = soundManager.GetSoundGroup(groupName);
if (group == null) { soundManager.AddSoundGroup(groupName); group = soundManager.GetSoundGroup(groupName); }

bool HasSoundGroup(SoundManager m, string name) => m.GetSoundGroup(name) != null;

try { soundManager.PlaySound(groupName, asset); } catch (GameFrameworkException ex) when (ex.Message.Contains("Sound group is invalid")) { Log.Error($"Sound group '{groupName}' does not exist"); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Sound agent helper is invalid.
• Sound helper is invalid.
• Asset name is invalid.
• Buffer is invalid.
• Bytes is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/994c9c1f386e320b. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Sound/SoundManager.SoundAgent.cs:38

            private readonly ISoundHelper m_SoundHelper;
            private readonly ISoundAgentHelper m_SoundAgentHelper;
            private int m_SerialId;
            private object m_SoundAsset;
            private DateTime m_SetSoundAssetTime;
            private bool m_MuteInSoundGroup;
            private float m_VolumeInSoundGroup;

            /// <summary>
            /// 初始化声音代理的新实例。
            /// </summary>
            /// <param name="soundGroup">所在的声音组。</param>
            /// <param name="soundHelper">声音辅助器接口。</param>
            /// <param name="soundAgentHelper">声音代理辅助器接口。</param>
            public SoundAgent(SoundGroup soundGroup, ISoundHelper soundHelper, ISoundAgentHelper soundAgentHelper)
            {
                if (soundGroup == null)
                {
                    throw new GameFrameworkException("Sound group is invalid.");
                }

                if (soundHelper == null)
                {
                    throw new GameFrameworkException("Sound helper is invalid.");
                }

                if (soundAgentHelper == null)
                {
                    throw new GameFrameworkException("Sound agent helper is invalid.");
                }

                m_SoundGroup = soundGroup;
                m_SoundHelper = soundHelper;
                m_SoundAgentHelper = soundAgentHelper;
                m_SoundAgentHelper.ResetSoundAgent += OnResetSoundAgent;
                m_SerialId = 0;
                m_SoundAsset = null;

View on GitHub (pinned to d0c010b051)