{"record":{"id":"8bdd089ab403b915","repo":"EllanJiang/GameFramework","slug":"load-sound-failure-asset-name-0-status-1-error-message-2","errorCode":null,"errorMessage":"Load sound failure, asset name '{0}', status '{1}', error message '{2}'.","messagePattern":"Load sound failure, asset name '(.+?)', status '(.+?)', error message '(.+?)'\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.cs","lineNumber":719,"sourceCode":"            }\n\n            m_SoundsBeingLoaded.Remove(playSoundInfo.SerialId);\n            string appendErrorMessage = Utility.Text.Format(\"Load sound failure, asset name '{0}', status '{1}', error message '{2}'.\", soundAssetName, status, errorMessage);\n            if (m_PlaySoundFailureEventHandler != null)\n            {\n                PlaySoundFailureEventArgs playSoundFailureEventArgs = PlaySoundFailureEventArgs.Create(playSoundInfo.SerialId, soundAssetName, playSoundInfo.SoundGroup.Name, playSoundInfo.PlaySoundParams, PlaySoundErrorCode.LoadAssetFailure, appendErrorMessage, playSoundInfo.UserData);\n                m_PlaySoundFailureEventHandler(this, playSoundFailureEventArgs);\n                ReferencePool.Release(playSoundFailureEventArgs);\n\n                if (playSoundInfo.PlaySoundParams.Referenced)\n                {\n                    ReferencePool.Release(playSoundInfo.PlaySoundParams);\n                }\n\n                return;\n            }\n\n            throw new GameFrameworkException(appendErrorMessage);\n        }\n\n        private void LoadAssetUpdateCallback(string soundAssetName, float progress, 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_PlaySoundUpdateEventHandler != null)\n            {\n                PlaySoundUpdateEventArgs playSoundUpdateEventArgs = PlaySoundUpdateEventArgs.Create(playSoundInfo.SerialId, soundAssetName, playSoundInfo.SoundGroup.Name, playSoundInfo.PlaySoundParams, progress, playSoundInfo.UserData);\n                m_PlaySoundUpdateEventHandler(this, playSoundUpdateEventArgs);\n                ReferencePool.Release(playSoundUpdateEventArgs);\n            }\n        }\n","sourceCodeStart":701,"sourceCodeEnd":737,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.cs#L701-L737","documentation":"SoundManager throws this in its LoadAssetFailureCallback when the asset system reports the sound asset could not be loaded. It appends the asset name, load status, and the underlying error message into a GameFrameworkException so the play-sound request fails loudly with full diagnostic context. It wraps the real root cause reported by the resource/asset loader.","triggerScenarios":"PlaySound/PlaySound3D was called with a soundAssetName that the ResourceComponent could not resolve or load (asset missing from build, not in resource catalog, load rule/type mismatch), and the failure callback surfaced the status and loader error.","commonSituations":"Sound asset renamed or moved without updating the asset name string; asset not marked as bundled/included in the Unity build; ResourceMode mismatch (package vs unpackaged resources); typo'd or procedurally-built asset path; calling PlaySound before resource initialization completes.","solutions":["Check the asset name and status in the message; verify the sound asset exists at that exact path and is included in the resource catalog/build.","Load the asset once with ResourceComponent/ResourceManager directly to see the underlying loader error.","Ensure resources are initialized/built for the current ResourceMode before playing sounds.","Wrap PlaySound and subscribe to PlaySoundDependencyAsset/PlaySound failure events to handle missing assets gracefully."],"exampleFix":"// before\nSoundComponent.PlaySound(\"Assets/Game/Sounds/explosion.wav\");\n// after\nif (ResourceComponent.HasAsset(\"Assets/Game/Sounds/explosion.wav\"))\n{\n    SoundComponent.PlaySound(\"Assets/Game/Sounds/explosion.wav\");\n}\nelse\n{\n    Log.Warning(\"Sound asset missing: Assets/Game/Sounds/explosion.wav\");\n}","handlingStrategy":"validation","validationCode":"// verify the asset exists before playing\nif (!resourceComponent.HasAsset(soundAssetName))\n{\n    Log.Warning(\"Sound asset not in catalog: \" + soundAssetName);\n    return;\n}","typeGuard":null,"tryCatchPattern":"try { soundComponent.PlaySound(serialId, soundAssetName, group); }\ncatch (GameFrameworkException ex) { Log.Error(\"PlaySound failed: \" + ex.Message); }","preventionTips":["Keep sound asset names as constants or an enum-backed table, never inline strings","Verify assets are included in the build's resource catalog","Initialize resource systems before any PlaySound call","Subscribe to play-sound failure events to log full context"],"tags":["unity","gameframework","sound","asset-loading"],"backgroundTag":"resource-not-found","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}