{"record":{"id":"d6bf9bb3564770a4","repo":"EllanJiang/GameFramework","slug":"reference-is-invalid","errorCode":null,"errorMessage":"Reference is invalid.","messagePattern":"Reference is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Base/ReferencePool/ReferencePool.cs","lineNumber":113,"sourceCode":"        /// 从引用池获取引用。\n        /// </summary>\n        /// <param name=\"referenceType\">引用类型。</param>\n        /// <returns>引用。</returns>\n        public static IReference Acquire(Type referenceType)\n        {\n            InternalCheckReferenceType(referenceType);\n            return GetReferenceCollection(referenceType).Acquire();\n        }\n\n        /// <summary>\n        /// 将引用归还引用池。\n        /// </summary>\n        /// <param name=\"reference\">引用。</param>\n        public static void Release(IReference reference)\n        {\n            if (reference == null)\n            {\n                throw new GameFrameworkException(\"Reference is invalid.\");\n            }\n\n            Type referenceType = reference.GetType();\n            InternalCheckReferenceType(referenceType);\n            GetReferenceCollection(referenceType).Release(reference);\n        }\n\n        /// <summary>\n        /// 向引用池中追加指定数量的引用。\n        /// </summary>\n        /// <typeparam name=\"T\">引用类型。</typeparam>\n        /// <param name=\"count\">追加数量。</param>\n        public static void Add<T>(int count) where T : class, IReference, new()\n        {\n            GetReferenceCollection(typeof(T)).Add<T>(count);\n        }\n\n        /// <summary>","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Base/ReferencePool/ReferencePool.cs#L95-L131","documentation":"ReferencePool.Release(IReference) checks its argument for null before routing the reference to its type's collection. Passing null means the caller has nothing to return to the pool — usually the result of a failed acquisition or an already-cleared field — and the framework rejects it immediately instead of failing later inside the collection.","triggerScenarios":"Calling ReferencePool.Release(null) — typically when the field holding the reference was never assigned, Acquire returned into a different variable than expected, or the reference was nulled by an earlier cleanup and Release is called unconditionally.","commonSituations":"Tear-down code that calls Release on a reference that failed to initialize; event handlers firing after the reference was already released and nulled; deserialization or spawn failures leaving the reference null before the cleanup path runs.","solutions":["Guard the Release call with a null check, or restructure so Release is only invoked on successfully acquired references.","Set the reference field to null right after Release and skip null fields in cleanup loops.","Trace why the reference was null at the call site — often an earlier Acquire/initialization failure that should be handled first."],"exampleFix":"// before\nReferencePool.Release(reference); // reference may be null\n\n// after\nif (reference != null)\n{\n    ReferencePool.Release(reference);\n    reference = null;\n}","handlingStrategy":"validation","validationCode":"if (reference != null)\n{\n    ReferencePool.Release(reference);\n    reference = null;\n}","typeGuard":"bool IsReleasable(IReference r) => r != null;","tryCatchPattern":"try { ReferencePool.Release(reference); }\ncatch (GameFrameworkException ex) when (ex.Message == \"Reference is invalid.\")\n{\n    // reference was null — investigate why acquire/init failed upstream\n}","preventionTips":["Always pair Acquire and Release in the same scope or owner object.","Null fields after Release and skip nulls in bulk cleanup loops.","Treat a null reference at Release time as a symptom of an earlier failed initialization; handle that failure at its source."],"tags":["object-pool","null-argument","reference-pool"],"backgroundTag":"null-argument","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"}