EllanJiang/GameFramework · error · GameFrameworkException

Sound group ' ' play sound ' ' failure.

Error message

Sound group '{0}' play sound '{1}' failure.

What it means

After a sound asset loads successfully, LoadAssetSuccessCallback asks the target sound group to play it. If the group's sound agent fails to play the asset (errorMessage set by ISoundHelper/agent), the manager releases the PlaySoundInfo and throws a GameFrameworkException reporting which group failed to play which sound.

Solutions

1. Verify soundAssetName points to a real AudioClip asset loadable by ResourceManager.
2. Check the custom ISoundHelper/SoundAgent Play implementation for conditions returning failure.
3. Ensure sound agent GameObjects (and their AudioSources) stay alive and enabled during playback.
4. Test the audio file format/codec on the target platform (e.g. certain formats unsupported on WebGL).

Example fix

// before
SoundManager.PlaySound("Assets/GameDev/UI/Button", "UI", 0); // not an AudioClip

// after
SoundManager.PlaySound("Assets/GameDev/Sounds/Button.wav", "UI", 0);

if (AssetDatabase.LoadAssetAtPath<AudioClip>(assetName) == null && Application.isEditor)
{
    Debug.LogError($"{assetName} is not an AudioClip");
}

try
{
    soundManager.PlaySound(assetName, groupName, priority);
}
catch (GameFrameworkException ex)
{
    Debug.LogError($"Failed to play '{assetName}': {ex.Message}");
}

When it happens

Trigger: The loaded asset is not a valid/playable AudioClip for the sound agent; the sound agent's hardware/audio source cannot start (missing AudioSource, destroyed agent GameObject); the helper's Play override returns failure.

Common situations: Passing a prefab or non-audio asset path as soundAssetName; custom SoundHelper returning false from Play on unsupported formats; device audio issues on target platform; agent destroyed mid-play.

Related errors

• Can not find sound ' '.
• Load sound failure, asset name
• Play sound info is invalid.
• Resource manager is invalid.
• Results is invalid.

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.cs:681

                m_PlaySoundFailureEventHandler(this, playSoundFailureEventArgs);
                ReferencePool.Release(playSoundFailureEventArgs);

                if (playSoundInfo.PlaySoundParams.Referenced)
                {
                    ReferencePool.Release(playSoundInfo.PlaySoundParams);
                }

                ReferencePool.Release(playSoundInfo);
                return;
            }

            if (playSoundInfo.PlaySoundParams.Referenced)
            {
                ReferencePool.Release(playSoundInfo.PlaySoundParams);
            }

            ReferencePool.Release(playSoundInfo);
            throw new GameFrameworkException(errorMessage);
        }

        private void LoadAssetFailureCallback(string soundAssetName, LoadResourceStatus status, string errorMessage, object userData)
        {
            PlaySoundInfo playSoundInfo = (PlaySoundInfo)userData;
            if (playSoundInfo == null)
            {
                throw new GameFrameworkException("Play sound info is invalid.");
            }

            if (m_SoundsToReleaseOnLoad.Contains(playSoundInfo.SerialId))
            {
                m_SoundsToReleaseOnLoad.Remove(playSoundInfo.SerialId);
                if (playSoundInfo.PlaySoundParams.Referenced)
                {
                    ReferencePool.Release(playSoundInfo.PlaySoundParams);
                }

View on GitHub (pinned to d0c010b051)