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
- Directory added without adding its meta file
- Meta file added without adding its Asset
- Asset deleted without deleting its meta file
- Directory deleted without deleting its meta file
- Meta file deleted without deleting its asset
- Asset renamed without renaming its meta file
- Meta file renamed without renaming its meta file
- Corrupt meta file contents
- Modified GUID in meta file
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
-
Always delete assets within the Unity Editor. This ensures that both the asset and its meta file are deleted together.
-
When staging deleted files for commit to git, make sure you include both the asset and its meta file.
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
-
When removing a directory from git, either by deleting its contents or by moving them elsewhere, make sure you delete the directory’s companion meta file.
-
Avoid creating empty asset directories in your Unity project as they won’t be tracked in git.
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
-
Always delete assets within the Unity Editor. This ensures that both the asset and its meta file are deleted together.
-
When staging deleted files for commit to git, make sure you include both the asset and its meta file.
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
-
Always rename assets within the Unity Editor. This ensures that both the asset and its meta file are renamed together.
-
When staging changes for commit to git, make sure you include both the renamed asset and its meta file.
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
-
Always rename assets within the Unity Editor. This ensures that both the renamed asset and its meta file are renamed together.
-
When staging changes for commit to git, make sure you include both the renamed asset and its meta file.
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?
- Drop us an email at support@ratelimited.io
- Raise an issue in our GitHub repository.
- Fill in our Contact Form
- Chat to our team on the MetaBuddy Discord Server