What causes "Sound group '{0}' is not exist." in EllanJiang/GameFramework?

Register the sound group first with SoundManager.AddSoundGroup(groupName, capacity) before adding agent helpers.

EllanJiang/GameFramework · error · GameFrameworkException

Sound group ' ' is not exist.

Error message

Sound group '{0}' is not exist.

What it means

SoundManager.AddSoundAgentHelper requires that the named sound group already exists before a sound agent helper can be added to it. GetSoundGroup returned null, meaning no group with that name was registered via AddSoundGroup. GameFramework throws a GameFrameworkException instead of failing silently.

Solutions

Register the sound group first with SoundManager.AddSoundGroup(groupName, capacity) before adding agent helpers.
Verify the group name string matches exactly (case, spelling, no whitespace) the name used in AddSoundGroup.
Check call ordering so AddSoundGroup runs before AddSoundAgentHelper (e.g. both in the same init sequence).
Null-check GetSoundGroup(name) before calling AddSoundAgentHelper and create the group on demand.

Example fix

// before
SoundManager.AddSoundAgentHelper("Music", soundAgentHelper);

// after
if (SoundManager.GetSoundGroup("Music") == null)
{
    SoundManager.AddSoundGroup("Music", 4);
}
SoundManager.AddSoundAgentHelper("Music", soundAgentHelper);

Defensive patterns

Strategy: validation

Validate before calling

if (soundManager.GetSoundGroup(groupName) == null)
{
    soundManager.AddSoundGroup(groupName, 4);
}

Prevention

Centralize sound group names in a constants class.
Create all sound groups in one init method that runs before agent wiring.
Never hardcode group names at call sites.

When it happens

Trigger: Calling AddSoundAgentHelper(soundGroupName, soundAgentHelper) with a group name that was never passed to AddSoundGroup, or after that group was removed, or with a misspelled/differently-cased name.

Common situations: Typo in the sound group name during Unity component wiring; calling AddSoundAgentHelper in Awake before the SoundComponent created the group; renaming a group in one place but not the other.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.cs:302

            return true;
        }

        /// <summary>
        /// 增加声音代理辅助器。
        /// </summary>
        /// <param name="soundGroupName">声音组名称。</param>
        /// <param name="soundAgentHelper">要增加的声音代理辅助器。</param>
        public void AddSoundAgentHelper(string soundGroupName, ISoundAgentHelper soundAgentHelper)
        {
            if (m_SoundHelper == null)
            {
                throw new GameFrameworkException("You must set sound helper first.");
            }

            SoundGroup soundGroup = (SoundGroup)GetSoundGroup(soundGroupName);
            if (soundGroup == null)
            {
                throw new GameFrameworkException(Utility.Text.Format("Sound group '{0}' is not exist.", soundGroupName));
            }

            soundGroup.AddSoundAgentHelper(m_SoundHelper, soundAgentHelper);
        }

        /// <summary>
        /// 获取所有正在加载声音的序列编号。
        /// </summary>
        /// <returns>所有正在加载声音的序列编号。</returns>
        public int[] GetAllLoadingSoundSerialIds()
        {
            return m_SoundsBeingLoaded.ToArray();
        }

        /// <summary>
        /// 获取所有正在加载声音的序列编号。
        /// </summary>
        /// <param name="results">所有正在加载声音的序列编号。</param>

View on GitHub (pinned to d0c010b051)