An infrequent, but potentially catastrophic problem that can occur is Unity unable to start up and open your project. I was helping a friend debug this exact problem yesterday. I have a checklist of things that I will generally do to debug the issue and see what the problem is:
But First
Before you do something like delete the project and restart from scratch: don’t. Unity keeps its underlying files in a few directories next to your files, and the two are very separate. There is usually no point in getting an older working version of the project, or re-checking out from version control.
Check the Log
When Unity starts up, even if you can’t see anything, it is actually logging out a lot of information to the editor log files. The help files contain the location of these logs for your operating system. Frequently the last couple lines of the log may contain useful information about the issue. Occasionally I have had the log tell me that Unity could not find my license information and just stop working. This seems to no longer happen in newer versions (5 and above) . But the log is the first place to look and see if anything in particular jumps out.
If you are on Mac the Editor.log is easy to find:
- Press Cmd-Space to open Spotlight and type ‘Console’.
- In Console on the right open the Arrow that says ‘~/Library/Logs’.
- Open the arrow that says ‘Unity’
- Click on Editor.log to view it.
You can also view it in Terminal (similar incantations are probably Linux-Friendly):
tail -f ~/Library/logs/Unity/Editor.log
Open Another Project.
It is possible to open multiple copies of Unity. This only works on Mac but holding the Option key down when starting Unity will bring you into the ‘Choose Project’ option. If you are able to open another project than the broken project, then you now know the problem is not Unity-specific, but project-specific. If the problem is Unity-specific, then you may want to look at re-installing Unity instead and focus less on debugging the project.
Delete the ScriptAssemblies Folder
While issues with the C# side of things rarely causes a hang, it can be useful to delete the Library/ScriptAssemblies folder which will cause Unity to recompile your code.
Nuking from Orbit.
Lastly, if nothing above works, it is possible to destroy all of Unity’s information on the project without destroying the project itself. This is actually very straightforward and easy to do, BUT will require Unity to do a full import of all data within the project (which can take some time if you have a big project). Because this may take some time I recommend opening a working project, going to Unity’s Preferences and unchecking ‘compress assets on import’. This will dramatically speed up the project re-import (especially iOS!).
- Shut down Unity.
- Then delete the ‘Library’ and ‘Temp’ folders of the hung project.
This will destroy all information Unity has about the project. Open up Unity and won’t use any of its old information and will re-build its data on the project from the ground up.
Memory Issues
This is more of an advanced issue to debug but it is possible for Unity to blow up because it runs out of memory on startup. I have only seen this happen on very large projects, but if you do not have a lot of memory this could theoretically happen on smaller projects. Watch the Editor.log file and you will see it print out that its out of memory. If this occurs the first thing to do is uncheck the ‘Compress Assets On Import’ option as this will dramatically lower memory requirements. If this still does not allow the project to open, then you can move parts of your projects out of the Assets/ folder and bring in Assets in smaller groups, allowing Unity to keep the asset crunching overhead reasonable.
Got Some Tips?
Have you had this happen to you? Do you have some information that could help other developers from pulling their hair out? Please leave a comment on Reddit!