EllanJiang/GameFramework · error · GameFrameworkException

Sound group ' ' is not exist. / Sound group ' ' is have no…

Error message

Sound group '{0}' is not exist. / Sound group '{0}' is have no sound agent.

What it means

When PlaySound is given a valid existing sound group, it asks the group for a free sound agent. If the group exists but has no sound agents (or none could accept the sound), the accumulated errorMessage, which reports either a missing sound group or a group with no sound agent, is thrown as a GameFrameworkException.

Solutions

  1. Verify the group name passed to PlaySound matches one created with AddSoundGroup.
  2. Add at least one sound agent to the group (AddSoundAgentHelper) so it can play sounds.
  3. Create the group with a positive sound agent count (AddSoundGroup(name, count)).
  4. Check GetSoundGroup(name) for null before PlaySound and create the group if absent.

Example fix

// before
SoundManager.PlaySound("BGM", "MusicGroup", 0); // group empty

// after
var group = SoundManager.GetSoundGroup("MusicGroup") ?? SoundManager.AddSoundGroup("MusicGroup", 2);
SoundManager.PlaySound("BGM", "MusicGroup", 0);
Defensive patterns

Strategy: validation

Validate before calling

if (soundManager.GetSoundGroup(groupName) == null)
{
    throw new InvalidOperationException($"Sound group '{groupName}' not configured");
}
soundManager.PlaySound(assetName, groupName, priority);

Try / catch

try
{
    soundManager.PlaySound(assetName, groupName, priority);
}
catch (GameFrameworkException ex)
{
    Debug.LogError($"Sound setup invalid: {ex.Message}");
}

Prevention

When it happens

Trigger: Calling PlaySound with a soundGroupName that does not exist, or with an existing group created with capacity 0 / no AddSoundAgentHelper calls, so no agent is available to play the sound.

Common situations: Sound group created via AddSoundGroup(name, 0) or agents never added; typo in group name passed to PlaySound; group created at runtime after sounds were configured for another name.

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/adc68b86dc589583. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Sound/SoundManager.cs:485

            }

            if (errorCode.HasValue)
            {
                if (m_PlaySoundFailureEventHandler != null)
                {
                    PlaySoundFailureEventArgs playSoundFailureEventArgs = PlaySoundFailureEventArgs.Create(serialId, soundAssetName, soundGroupName, playSoundParams, errorCode.Value, errorMessage, userData);
                    m_PlaySoundFailureEventHandler(this, playSoundFailureEventArgs);
                    ReferencePool.Release(playSoundFailureEventArgs);

                    if (playSoundParams.Referenced)
                    {
                        ReferencePool.Release(playSoundParams);
                    }

                    return serialId;
                }

                throw new GameFrameworkException(errorMessage);
            }

            m_SoundsBeingLoaded.Add(serialId);
            m_ResourceManager.LoadAsset(soundAssetName, priority, m_LoadAssetCallbacks, PlaySoundInfo.Create(serialId, soundGroup, playSoundParams, userData));
            return serialId;
        }

        /// <summary>
        /// 停止播放声音。
        /// </summary>
        /// <param name="serialId">要停止播放声音的序列编号。</param>
        /// <returns>是否停止播放声音成功。</returns>
        public bool StopSound(int serialId)
        {
            return StopSound(serialId, Constant.DefaultFadeOutSeconds);
        }

        /// <summary>

View on GitHub (pinned to d0c010b051)