{"record":{"id":"a36b4f93162a48b0","repo":"EllanJiang/GameFramework","slug":"sound-group-0-play-sound-1-failure","errorCode":null,"errorMessage":"Sound group '{0}' play sound '{1}' failure.","messagePattern":"Sound group '(.+?)' play sound '(.+?)' failure\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.cs","lineNumber":681,"sourceCode":"                m_PlaySoundFailureEventHandler(this, playSoundFailureEventArgs);\n                ReferencePool.Release(playSoundFailureEventArgs);\n\n                if (playSoundInfo.PlaySoundParams.Referenced)\n                {\n                    ReferencePool.Release(playSoundInfo.PlaySoundParams);\n                }\n\n                ReferencePool.Release(playSoundInfo);\n                return;\n            }\n\n            if (playSoundInfo.PlaySoundParams.Referenced)\n            {\n                ReferencePool.Release(playSoundInfo.PlaySoundParams);\n            }\n\n            ReferencePool.Release(playSoundInfo);\n            throw new GameFrameworkException(errorMessage);\n        }\n\n        private void LoadAssetFailureCallback(string soundAssetName, LoadResourceStatus status, string errorMessage, object userData)\n        {\n            PlaySoundInfo playSoundInfo = (PlaySoundInfo)userData;\n            if (playSoundInfo == null)\n            {\n                throw new GameFrameworkException(\"Play sound info is invalid.\");\n            }\n\n            if (m_SoundsToReleaseOnLoad.Contains(playSoundInfo.SerialId))\n            {\n                m_SoundsToReleaseOnLoad.Remove(playSoundInfo.SerialId);\n                if (playSoundInfo.PlaySoundParams.Referenced)\n                {\n                    ReferencePool.Release(playSoundInfo.PlaySoundParams);\n                }\n","sourceCodeStart":663,"sourceCodeEnd":699,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.cs#L663-L699","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify soundAssetName points to a real AudioClip asset loadable by ResourceManager.","Check the custom ISoundHelper/SoundAgent Play implementation for conditions returning failure.","Ensure sound agent GameObjects (and their AudioSources) stay alive and enabled during playback.","Test the audio file format/codec on the target platform (e.g. certain formats unsupported on WebGL)."],"exampleFix":"// before\nSoundManager.PlaySound(\"Assets/GameDev/UI/Button\", \"UI\", 0); // not an AudioClip\n\n// after\nSoundManager.PlaySound(\"Assets/GameDev/Sounds/Button.wav\", \"UI\", 0);","handlingStrategy":"try-catch","validationCode":"if (AssetDatabase.LoadAssetAtPath<AudioClip>(assetName) == null && Application.isEditor)\n{\n    Debug.LogError($\"{assetName} is not an AudioClip\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    soundManager.PlaySound(assetName, groupName, priority);\n}\ncatch (GameFrameworkException ex)\n{\n    Debug.LogError($\"Failed to play '{assetName}': {ex.Message}\");\n}","preventionTips":["Reference audio through generated asset-name constants, not hand-typed paths.","Validate custom ISoundHelper.Play implementations return true only on real success.","Test sound playback on every target platform early in development."],"tags":["sound","gameframework","playback-failure","audio"],"backgroundTag":"operation-failed","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"}