MetaBuddy Logo

Meta File Errors (and how to fix them)

At present MetaBuddy detects 10 different types of meta file error.

Below you can find each of the individual errors detected by MetaBuddy along with instructions for fixing and avoiding them in the future.

Asset added without adding its meta file

This error occurs when you add an asset in your Unity project to git without adding its companion .meta file.

For example, if you added an asset file Assets/Textures/Explosion.png to git, you should also add its companion meta file Assets/Textures/Explosion.png.meta

The meta file is important because it contains the GUID that Unity uses to keep track of the asset as well as any settings associated with the asset (for instance, which mode to compress a texture with).

How to fix this error

Usually when you see this error, the meta file for the asset already exists and you just need to stage it for addition to git with git add <META-FILENAME> or your git client’s equivalent.

For example git add Assets/Textures/Explosion.png.meta

How to avoid in the future

When adding new assets to git, make sure you add both the asset and its meta file.

Directory added without adding its meta file

This error occurs when you add an asset directory to your Unity project without adding its companion .meta file to git.

Git doesn’t keep track of directories explicitly, only files. However, when you add a file in a new directory to git, that directory will be implicitly added.

For example, if you add a new asset file Assets/Textures/Explosion.png to git, this implicitly adds the directory Assets/Textures if that directory didn’t already exist. When this happens you should also add the companion meta file for the new directory Assets/Textures.meta.

How to fix this error

Usually when you see this error, the meta file for the directory already exists and you just need to stage it for addition to git with git add <META-FILENAME> or your git client’s equivalent.

For example git add Assets/Textures.meta

How to avoid in the future

When adding assets in new directories to git, make sure you add the meta files for those new directories.

Meta file added without adding its Asset

This error occurs when you add the meta file for an asset in your Unity project to git without adding the asset itself.

For example, if you added a meta file Assets/Textures/Explosion.png.meta to git, you should also add its corresponding asset file Assets/Textures/Explosion.png

How to fix this error

Usually when you see this error, the asset file already exists and you just need to stage it for addition to git with git add <ASSET-FILENAME> or your git client’s equivalent command.

For example git add Assets/Textures/Explosion.png

How to avoid in the future

When staging new assets for commit to git, make sure you add both the asset and its meta file.

Asset deleted without deleting its meta file

This error occurs when you delete an asset in your Unity project from git without deleting its companion .meta file.

For example, if you deleted an asset file Assets/Textures/Explosion.png from git, you should also delete its companion meta file Assets/Textures/Explosion.png.meta so that you don’t leave an orphaned meta file in your git repository.

How to fix this error

To fix this error you need to stage the meta file for deletion from git with git rm <META-FILENAME> or your git client’s equivalent command.

For example git rm Assets/Textures/Explosion.png.meta

How to avoid in the future

Directory deleted without deleting its meta file

This error occurs when an asset directory in your Unity project is deleted from git without deleting its companion .meta file.

Git doesn’t track directories explicitly, only files. However, it does track directories implicitly, so when all of a directory’s contents are deleted, that directory is also removed from your git repo.

For example, if you deleted all of the files and sub-directories of the directory Assets/Textures from git, you should also delete its companion meta file Assets/Textures.meta so that you don’t leave an orphaned meta file in your git repository.

How to fix this error

To fix this error you need to stage the directory’s meta file for deletion from git with git rm <META-FILENAME> or your git client’s equivalent command.

For example git rm Assets/Textures.meta

How to avoid in the future

Meta file deleted without deleting its asset

This error occurs when you delete a meta file in your Unity project from git without deleting the corresponding asset file.

For example, if you deleted a meta file Assets/Textures/Explosion.png.meta to git, you should also delete its companion asset file Assets/Textures/Explosion.png

How to fix this error

To fix this error you need to stage the asset for deletion from git with git rm <ASSET-FILENAME> or your git client’s equivalent command.

For example git rm Assets/Textures/Explosion.png

How to avoid in the future

Asset renamed without renaming its meta file

This error occurs when you rename an asset in your Unity project without renaming the corresponding meta file.

For example, if you renamed an asset Assets/Textures/Explosion.png to Assets/Textures/Bang.png in git, you should also rename its companion meta file Assets/Textures/Bang.png.meta

How to fix this error

This error usually occurs because you have forgotten to stage the renamed meta file for commit to git. If this is the case you need to stage the renamed meta file for commit to git with git add <META-FILENAME> or your git client’s equivalent command.

For example git rm Assets/Textures/Bang.png.meta

How to avoid in the future

Meta file renamed without renaming its meta file

This error occurs when you rename a meta file in your Unity project without renaming the corresponding asset file.

For example, if you renamed a meta file Assets/Textures/Explosion.png.meta to Assets/Textures/Bang.png.meta in git, you should also rename its companion asset Assets/Textures/Bang.png

How to fix this error

To fix this error you need to stage the renamed asset for commit to git with git add <ASSET-FILENAME> or your git client’s equivalent command.

For example git rm Assets/Textures/Bang.png

How to avoid in the future

Corrupt meta file contents

This error occurs when the contents of meta file become corrupted so that they can no longer be read by Unity.

This error is often caused when git detected conflicts in a meta file during a merge, but those conflicts weren’t resolved properly.

When git detects conflicts in a file it writes both versions of the conflicted it to the line like this:

fileFormatVersion: 2
<<<<<<< HEAD:Explosion.png.meta
guid: ba4d185bfb5b94901b6da824bfbfe6fa
=======
guid: abc45129ef91683ac929b93458652185
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:Explosion.png.meta
NativeFormatImporter:
  externalObjects: {}
...

In the above example, git detected a conflict on the line starting guid: so it wrote both versions of this line to the file, surrounded by markers <<<<<<<, ======= and >>>>>>> to draw your attention to the conflict.

Git expects you to resolve the conflict by editing the file to include either one version of conflicted lines or the other, but not both versions.

Once you have fixed the conflict you then notify git that it has been dealt with by re-adding it with git add <CONFLICTED-FILENAME> or your git client’s equivalent command.

But, if you re-add the file without resolving the conflicts, the markers remain, making the file unreadable by Unity and triggering this error.

How to fix this error

To fix this error you need to edit the affected meta file in a text editor, removing the conflict markers along with one version of the conflicted lines to resolve the conflict.

Continuing with the above example, we might choose to take the remote (HEAD) version of the conflicted lines as follows:

fileFormatVersion: 2
guid: ba4d185bfb5b94901b6da824bfbfe6fa
NativeFormatImporter:
  externalObjects: {}
...

Now that we have resolved the conflict and removed the conflict markers, the file becomes readable again. Now we can re-add the resolved file to fix the error.

N.B. Whenever you resolve conflicts like this, you should test your changes in the Unity Editor to make sure that everything still works as expected.

How to avoid in the future

When git notifies you of a conflicted meta file during a merge, make sure you fix the conflict before re-adding the file it to git.

If you re-add the file without fixing the conflict, the meta file will become broken and unreadable by Unity.

Modified GUID in meta file

Unity keeps track of the assets in your project using Globally Unique Identifiers (GUIDs) which are stored in each asset’s meta file. GUIDs are long hex strings that look something like this ba4d185bfb5b94901b6da824bfbfe6fa

For instance, when you reference one asset from another, Unity saves the reference by storing the GUID of the referenced asset.

An advantage of this approach is that you can rename and move the assets within your project without breaking references between them.

For instance, if you rename the asset Assets/Textures/Explosion.png to Assets/Textures/Bang.png in the Unity Editor, any references to that asset will remain intact.

This error is usually caused when you update an asset by deleting it and then creating a new asset with the same name. When you do this, Unity gives the new asset a different GUID to the old one, because, in Unity’s eyes, it is a completely new asset, even though it has the same name as the original.

When this happens, the new asset has a different GUID to the one it replaces, so any references to the old asset will become broken.

This is almost never what you want.

How to fix this error

Caution: This fix will lose any changes you have made to the affected assets’s settings that you see in the Inspector window.

The easiest way to fix this error is to revert your changes to the asset’s meta file with git checkout <META-FILENAME> or your git client’s equivalent command.

This will restore the GUID to its original value, but it will also revert any changes you have made to the asset’s settings that you see in the Inspector window.

So, if you apply this fix, you will have to reapply any changes that you have to asset’s settings once the meta file has been reverted.

This is a pain and is something we hope to fix with MetaBuddy’s automatic fixes feature.

How to avoid in the future

Avoid updating assets by deleting and re-creating them.

Instead use the Reimport option on the asset’s context menu to update the asset contents without changing its GUID or settings from the Inspector window.

Support

Got questions? Need help?