EllanJiang/GameFramework · error · GameFrameworkException

Reference is invalid.

Error message

Reference is invalid.

What it means

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.

Solutions

1. Guard the Release call with a null check, or restructure so Release is only invoked on successfully acquired references.
2. Set the reference field to null right after Release and skip null fields in cleanup loops.
3. Trace why the reference was null at the call site — often an earlier Acquire/initialization failure that should be handled first.

Example fix

// before
ReferencePool.Release(reference); // reference may be null

// after
if (reference != null)
{
    ReferencePool.Release(reference);
    reference = null;
}

if (reference != null)
{
    ReferencePool.Release(reference);
    reference = null;
}

bool IsReleasable(IReference r) => r != null;

try { ReferencePool.Release(reference); }
catch (GameFrameworkException ex) when (ex.Message == "Reference is invalid.")
{
    // reference was null — investigate why acquire/init failed upstream
}

When it happens

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

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

Related errors

• Reference type is invalid.
• ReferenceType is invalid.
• Type is invalid.
• The reference has been released.
• Reference type is not a non-abstract class type.

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

Appendix: source

Thrown at GameFramework/Base/ReferencePool/ReferencePool.cs:113

        /// 从引用池获取引用。
        /// </summary>
        /// <param name="referenceType">引用类型。</param>
        /// <returns>引用。</returns>
        public static IReference Acquire(Type referenceType)
        {
            InternalCheckReferenceType(referenceType);
            return GetReferenceCollection(referenceType).Acquire();
        }

        /// <summary>
        /// 将引用归还引用池。
        /// </summary>
        /// <param name="reference">引用。</param>
        public static void Release(IReference reference)
        {
            if (reference == null)
            {
                throw new GameFrameworkException("Reference is invalid.");
            }

            Type referenceType = reference.GetType();
            InternalCheckReferenceType(referenceType);
            GetReferenceCollection(referenceType).Release(reference);
        }

        /// <summary>
        /// 向引用池中追加指定数量的引用。
        /// </summary>
        /// <typeparam name="T">引用类型。</typeparam>
        /// <param name="count">追加数量。</param>
        public static void Add<T>(int count) where T : class, IReference, new()
        {
            GetReferenceCollection(typeof(T)).Add<T>(count);
        }

        /// <summary>

View on GitHub (pinned to d0c010b051)