Avoiding Broken References in Unity Projects

How do references get broken?

The Unity Editor never asks us to work with GUIDs directly. In fact we rarely see them in the Editor, even in error messages. They are simply a mechanism that Unity uses behind the scenes to tie the various pieces of our project together.

Unity also does a great job of keeping our Asset’s meta files paired together with their associated content, ensuring that any create, rename, move and delete operations are applied to both of the files in the pair.

So, Unity is so good at managing meta files and GUIDs, how do our references get broken?

 There are to principle causes of broken references:

  • Expecting Assets to be identified by the name rather than GUID.
  • Separating Assets from their .meta files.

In the rest of this article, we will look at how these causes occur and show how you can avoid them in your project.

Cause 1: Deleting and recreating Assets under the same name

This type of breakage happens when, instead of modifying an Asset in place, we delete it in the Editor and then recreate it with the same name, expecting any references to it to remain intact.

The new Asset has the same name as the original so everything should be good right?

Not so 😧. Remember Unity doesn’t care about the name of your Asset because it uses GUIDs, not names, as identifiers.

When you delete an Asset, Unity throws away the meta file containing that Asset’s GUID. When you recreate the Asset, even under the same name, Unity generates a new meta file containing a new GUID.

diagram showing how deleting and recreating an asset changes its guid

Unity sees the new Asset as something completely new and unrelated to the original, even though they share a name. Hence, any references to the original Asset are broken because they point to a GUID that doesn’t exist any more.

To avoid this type of breakage you can adopt the following practices:

1.1. Prefer modifying Assets in place over deleting and recreating them.

It’s fine to change an Asset’s content file (eg. Fire.png) as long as you don’t separate it from its .meta file.

1.2. If you accidentally delete an Asset, don’t recreate it manually.

 Pro tip: Instead, restore the original from your version control system using git checkout <FILENAME> or equivalent. That way its GUID will be preserved and any references to will remain intact.

Cause 2: Moving and renaming assets outside the Unity Editor

While moving and renaming assets outside of Unity Editor, for instance in Windows Explorer or macOS Finder, doesn’t guarantee reference breakages, it certainly increases the risk of them occurring.

The reason for this is that when you modify assets outside of the Editor, there is a possibility that you separate an asset from its meta file. When this happens the Asset loses its GUID and any links to it become broken.

To avoid this type of breakage you can adopt the following practices:

2.1. Prefer using the Unity Editor creating, moving, renaming and deleting Assets.

This guarantees that meta files are kept in sync with their associated content.

 Pro tip: The Unity Editor is good at working with Asset files, just let it do its thing.

2.2. If you must change an Asset outside Unity, make sure you close the Unity Editor while you do so.

This avoids the Editor becoming confused if you temporarily separate a file from its .meta, for instance if you move files one at a time.

If the Editor sees an Asset without a .meta or a .meta without an Asset, it will “helpfully” intervene, either creating or deleting the .meta file.

2.3. Be extra careful when renaming files.

The prefixes of the two files in an Asset need to match exactly for Unity to associate them. The meta file for Fire.png should be Fire.png.meta not fire.png.meta or fire.PNG.meta

If the names don’t match, Unity can’t associate the Asset with its .meta file. This usually leads to a new .meta file being created, with a new GUID. And as we saw above, changing GUIDs causes broken references.

diagram showing broken reference between unity assets with meta file and guid

Cause 3: Forgetting to add Asset files to version control

When we add a new Asset to our version control it’s important that we add both the Asset file and its accompanying meta file.

If we commit one without the other, we have effectively separated the two files comprising the Asset for anyone who pulls our change.

This cause is especially insidious because the developer who forgot a file won’t see anything wrong. Both of the files exist on their machine and everything looks as expected.

We may not detect the issue until other team members pull the change and start seeing phantom changes appear in version control.

We can address this cause by doing the following:

3.1 Use a checklist or tooling to catch mistakes

By having your team check their files before committing, you catch mistakes at source and reduce the odds of a bad commit affecting the rest of the team.

There are two principle ways of achieving this; a pre-commit checklist that developers follow each time they commit, or a tool that automates the checking process.

meta buddy screenshot

 Pro tip: Our pre-commit checklist is a good place to start for small teams. Its lightweight and free.

If your team is larger (or you just hate manual processes), you might want to try our MetaBuddy plugin for Unity.

3.2 If you do forget an Asset file, stop the line

If someone does push a bad commit with missing file, the quicker you stop and fix it, the less disruption your team is going to suffer.

We recommend stopping the line to diagnose and fix the issue as soon as you detect it.

Summary and next steps

In this article we have described the common causes of broken references in Unity projects and best practices to avoid them.

If you want to learn more about Asset files, meta files and how Unity uses them in your projects, check out our more detailed guides: Understanding meta files and GUIDs and Unity meta file Deep Dive