Unity’s coroutines are a powerful way to run tasks asynchronously over multiple frames. However, improper use of coroutines can lead to memory leaks and performance issues. One of the most common problems occurs when coroutines continue running after the objects they reference are destroyed, leading to memory leaks, null references, and unexpected behavior.

What Is a Coroutine Memory Leak in Unity?

A coroutine memory leak happens when a coroutine holds a reference to a GameObject, component, or other object that has been destroyed, preventing the garbage collector from releasing memory. Over time, this can cause the application to consume more memory, potentially slowing down your game or even causing crashes.

Common symptoms include:

• Memory usage increasing steadily in the profiler even though objects are destroyed.
• Coroutines continuing to run on destroyed objects.
• Frequent MissingReferenceException or NullReferenceException errors in the console.

Why This Happens

Unity coroutines maintain references to the objects they are running on. If you start a coroutine on a GameObject and that object is destroyed before the coroutine finishes, Unity cannot automatically clean up the coroutine. Additionally, if you store references to coroutines in lists or dictionaries without stopping them, they will remain in memory indefinitely.

Common Causes of Coroutine Memory Leaks

1. Starting Coroutines Without Stopping Them

If you start a coroutine but never stop it before the object is destroyed:

IEnumerator ExampleCoroutine() {
    while(true) {
        yield return new WaitForSeconds(1f);
        Debug.Log("Running...");
    }
}

// Started on an object
StartCoroutine(ExampleCoroutine());

If the GameObject is destroyed, the coroutine may continue referencing the object in memory.

2. Using Anonymous Coroutines

Starting coroutines inline without keeping a reference makes it impossible to stop them later:

StartCoroutine(SomeCoroutineMethod(() => {
    Debug.Log("Anonymous Coroutine running");
}));

Since you don’t have a reference, you cannot stop this coroutine when needed, causing leaks.

3. Coroutines Holding References to Destroyed Objects

Passing a GameObject or component into a coroutine can keep it alive even after destruction:

IEnumerator MoveObject(GameObject obj) {
    while(obj != null) {
        obj.transform.position += Vector3.forward * Time.deltaTime;
        yield return null;
    }
}

If obj is destroyed but the coroutine continues, it may cause a memory leak.

How to Identify Coroutine Memory Leaks

Unity provides tools to track memory and coroutine issues:

1. Use the Profiler

Open the Unity Profiler and monitor memory usage. If memory keeps increasing over time despite destroying objects, coroutines may be holding references.

2. Check for Exceptions in the Console

Repeated MissingReferenceException or NullReferenceException messages during gameplay indicate coroutines are referencing destroyed objects.

3. Use Coroutine References

Store references to coroutines when starting them:

Coroutine myCoroutine = StartCoroutine(MyCoroutine());

This makes it easier to stop them later and check if they are still running.

How to Fix Coroutine Memory Leaks

1. Stop Coroutines on Object Destruction

Use OnDestroy() to stop coroutines:

private Coroutine myCoroutine;

void Start() {
    myCoroutine = StartCoroutine(MyCoroutine());
}

void OnDestroy() {
    if(myCoroutine != null) {
        StopCoroutine(myCoroutine);
    }
}

IEnumerator MyCoroutine() {
    while(true) {
        yield return new WaitForSeconds(1f);
        Debug.Log("Running...");
    }
}

2. Use Null Checks Inside Coroutines

Check if the object is null before accessing it:

IEnumerator MoveObject(GameObject obj) {
    while(obj != null) {
        obj.transform.position += Vector3.forward * Time.deltaTime;
        yield return null;
    }
}

This ensures that the coroutine exits gracefully if the object is destroyed.

3. Avoid Anonymous or Inline Coroutines for Long-Running Tasks

Always assign coroutines to a variable so you can stop them later:

Coroutine movementCoroutine;

void Start() {
    movementCoroutine = StartCoroutine(MoveObject(player));
}

void OnDisable() {
    if(movementCoroutine != null) StopCoroutine(movementCoroutine);
}

4. Centralize Coroutine Management

Use a manager class to track coroutines across objects. This ensures they can be stopped collectively when needed, reducing memory leaks.

Best Practices for Using Coroutines Safely

• Always stop coroutines when an object is destroyed or disabled.
• Store references to all coroutines you start.
• Use null checks within coroutines before accessing object properties.
• Avoid anonymous or inline coroutines for long-running tasks.
• Use manager classes for global or persistent coroutines.
• Regularly profile memory usage to catch leaks early.

Conclusion

Coroutines are a powerful tool in Unity, but improper use can lead to memory leaks and unstable behavior. By storing coroutine references, stopping them on object destruction, using null checks, and avoiding anonymous coroutines for persistent tasks, you can prevent memory leaks and ensure your Unity projects remain efficient and stable.

Understanding how coroutines reference objects and managing them carefully is key to writing clean, leak-free Unity code.