{"record":{"id":"801b81948c791b17","repo":"EllanJiang/GameFramework","slug":"sound-agent-helper-is-invalid","errorCode":null,"errorMessage":"Sound agent helper is invalid.","messagePattern":"Sound agent helper is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Sound/SoundManager.SoundAgent.cs","lineNumber":48,"sourceCode":"            /// </summary>\n            /// <param name=\"soundGroup\">所在的声音组。</param>\n            /// <param name=\"soundHelper\">声音辅助器接口。</param>\n            /// <param name=\"soundAgentHelper\">声音代理辅助器接口。</param>\n            public SoundAgent(SoundGroup soundGroup, ISoundHelper soundHelper, ISoundAgentHelper soundAgentHelper)\n            {\n                if (soundGroup == null)\n                {\n                    throw new GameFrameworkException(\"Sound group is invalid.\");\n                }\n\n                if (soundHelper == null)\n                {\n                    throw new GameFrameworkException(\"Sound helper is invalid.\");\n                }\n\n                if (soundAgentHelper == null)\n                {\n                    throw new GameFrameworkException(\"Sound agent helper is invalid.\");\n                }\n\n                m_SoundGroup = soundGroup;\n                m_SoundHelper = soundHelper;\n                m_SoundAgentHelper = soundAgentHelper;\n                m_SoundAgentHelper.ResetSoundAgent += OnResetSoundAgent;\n                m_SerialId = 0;\n                m_SoundAsset = null;\n                Reset();\n            }\n\n            /// <summary>\n            /// 获取所在的声音组。\n            /// </summary>\n            public ISoundGroup SoundGroup\n            {\n                get\n                {","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Sound/SoundManager.SoundAgent.cs#L30-L66","documentation":"The SoundAgent constructor requires a non-null ISoundAgentHelper — the platform-specific audio playback adapter (e.g. Unity sound agent helper). Without it the agent has no playback engine, and it also subscribes ResetSoundAgent on it, so a null value would crash later; construction therefore throws immediately.","triggerScenarios":"Constructing SoundAgent(soundGroup, soundHelper, null) — when an agent is created without a valid agent helper, e.g. custom agent pool code or a factory returning null helpers after a failed asset load.","commonSituations":"Custom ISoundAgentHelper implementations that fail to instantiate (missing component on prefab, AddComponent failure) and the null result is passed along; modified SoundManager agent-creation loops that skip helper assignment.","solutions":["Ensure a concrete ISoundAgentHelper (e.g. Unity SoundAgentHelper attached to a GameObject) is created and passed for each agent.","If helpers come from a factory/pool, null-check the returned helper before constructing the agent and treat null as an allocation failure.","Verify the sound agent prefab still has the helper MonoBehaviour component after prefab changes."],"exampleFix":"// before\nvar helper = go.GetComponent<SoundAgentHelper>(); // may be null\nvar agent = new SoundAgent(group, soundHelper, helper);\n// after\nvar helper = go.GetComponent<SoundAgentHelper>();\nif (helper == null) { helper = go.AddComponent<SoundAgentHelper>(); }\nvar agent = new SoundAgent(group, soundHelper, helper);","handlingStrategy":"type-guard","validationCode":"var agentHelper = go.GetComponent<SoundAgentHelper>();\nif (agentHelper == null) agentHelper = go.AddComponent<SoundAgentHelper>();","typeGuard":"ISoundAgentHelper EnsureHelper(GameObject go) => go.GetComponent<SoundAgentHelper>() ?? go.AddComponent<SoundAgentHelper>();","tryCatchPattern":"try { var agent = new SoundAgent(group, soundHelper, agentHelper); } catch (GameFrameworkException ex) when (ex.Message.Contains(\"Sound agent helper is invalid\")) { Log.Fatal(\"Sound agent helper missing on agent GameObject\"); throw; }","preventionTips":["Verify agent prefabs keep the helper component","Null-check factory/pool results before constructing agents","Cover agent creation with an edit-mode prefab test"],"tags":["gameframework","audio","null-argument","sound-agent"],"backgroundTag":"null-argument","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"}