EllanJiang/GameFramework · error · GameFrameworkException

Load sound failure, asset name

Error message

Load sound failure, asset name '{0}', status '{1}', error message '{2}'.

What it means

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.

Solutions

1. 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.
2. Load the asset once with ResourceComponent/ResourceManager directly to see the underlying loader error.
3. Ensure resources are initialized/built for the current ResourceMode before playing sounds.
4. Wrap PlaySound and subscribe to PlaySoundDependencyAsset/PlaySound failure events to handle missing assets gracefully.

Example fix

// before
SoundComponent.PlaySound("Assets/Game/Sounds/explosion.wav");
// after
if (ResourceComponent.HasAsset("Assets/Game/Sounds/explosion.wav"))
{
    SoundComponent.PlaySound("Assets/Game/Sounds/explosion.wav");
}
else
{
    Log.Warning("Sound asset missing: Assets/Game/Sounds/explosion.wav");
}

// verify the asset exists before playing
if (!resourceComponent.HasAsset(soundAssetName))
{
    Log.Warning("Sound asset not in catalog: " + soundAssetName);
    return;
}

try { soundComponent.PlaySound(serialId, soundAssetName, group); }
catch (GameFrameworkException ex) { Log.Error("PlaySound failed: " + ex.Message); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Task agent is invalid.
• Results is invalid.
• Offset is invalid.
• Length is invalid.
• Delta length is invalid.

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

Appendix: source

Thrown at GameFramework/Sound/SoundManager.cs:719

            }

            m_SoundsBeingLoaded.Remove(playSoundInfo.SerialId);
            string appendErrorMessage = Utility.Text.Format("Load sound failure, asset name '{0}', status '{1}', error message '{2}'.", soundAssetName, status, errorMessage);
            if (m_PlaySoundFailureEventHandler != null)
            {
                PlaySoundFailureEventArgs playSoundFailureEventArgs = PlaySoundFailureEventArgs.Create(playSoundInfo.SerialId, soundAssetName, playSoundInfo.SoundGroup.Name, playSoundInfo.PlaySoundParams, PlaySoundErrorCode.LoadAssetFailure, appendErrorMessage, playSoundInfo.UserData);
                m_PlaySoundFailureEventHandler(this, playSoundFailureEventArgs);
                ReferencePool.Release(playSoundFailureEventArgs);

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

                return;
            }

            throw new GameFrameworkException(appendErrorMessage);
        }

        private void LoadAssetUpdateCallback(string soundAssetName, float progress, object userData)
        {
            PlaySoundInfo playSoundInfo = (PlaySoundInfo)userData;
            if (playSoundInfo == null)
            {
                throw new GameFrameworkException("Play sound info is invalid.");
            }

            if (m_PlaySoundUpdateEventHandler != null)
            {
                PlaySoundUpdateEventArgs playSoundUpdateEventArgs = PlaySoundUpdateEventArgs.Create(playSoundInfo.SerialId, soundAssetName, playSoundInfo.SoundGroup.Name, playSoundInfo.PlaySoundParams, progress, playSoundInfo.UserData);
                m_PlaySoundUpdateEventHandler(this, playSoundUpdateEventArgs);
                ReferencePool.Release(playSoundUpdateEventArgs);
            }
        }

View on GitHub (pinned to d0c010b051)