Recursive Thoughts

Thoughts, stories and ideas.

Mildly painful solution to Unity3d's meta GUID hell

When working on a Unity3d project with a team, no matter how meticulously you keep track of your meta files, the occasional missing file/shader/material will happen.

The problem happens when someone forgets to commit a meta file, but does commit the file it belonged to.

For example one commits <some_material>.mat but not its <some_material>.mat.meta

When others pull down the changes they'll get the file, but not the meta-file.
In that case Unity will create a new meta file with a different GUID, so it won't recognise the material file as the same file across the different workspaces anymore.

When it happens sometimes a console warning similar to this will be shown:
The GUID for Assets/Resources/Materials/<some_material>.mat is already in use by Assets/Resources/Materials/<some_material>1.mat. Assigning a new guid. But I find that it's easy enough to overlook that warning if you're not keeping an eye on the console.
One console clean and it's gone forever.

The most annoying symptom of mismatching GUIDs between workspaces is when a reference to the file is put in a scene. When opening that scene from the other workspace (with the different guid) the reference will be missing, even though the file it refers to is actually in the project, which can be quite puzzling.

In particularly stubborn cases it's not enough to make sure the GUID matches, because the Library will retain the error.

Assuming you have a reference workspace where you're going to correct the error and then push to version control, the solution then is:

  1. close unity on reference workspace
  2. delete broken meta files
  3. delete library
  4. open unity
  5. wait while the library is re-created
  6. make sure to add the meta files to version control
  7. put the right reference in the scenes again (eg. material on a renderer)
  8. commit new meta files and changed scenes
  9. close unity on the machines receiving changes
  10. delete library on those machines
  11. get latest version from version control
  12. reopen unity
  13. wait for library to be remade

That should do it.

Show Comments