Here’s some proven (but not guaranteed to help in every situation) troubleshooting steps to take when you run into one of the common yet ‘out of the ordinary’ issues. Read: not NullReferenceException but inexplicable install failures or compile errors.
General Tips to Avoid Issues
These tips are best practice to prevent any future issues down the line:
- exclude the project and unity install folders from all antivirus live/online scans
- ensure you have enough free disk space on both project and OS drives at all times (recommended min. 20 GiB free)
- ensure your system meets the hardware and operation system requirements
- ensure you have the latest security updates installed
- Caution: if Windows Update fails to install some or all updates this may indicate that the system is generally broken or has been tampered with (possibly malware and no, those aren’t necessarily detected by antivirus)
- ensure you have the latest graphics driver installed
- AMD GPU: prefer the “PRO” driver
- Nvidia GPU: prefer the “Studio” driver
- Intel integrated graphics: you may have issues regardless of driver version, more so the older the CPU is.
- do not tamper with your operating system and do not use tools that do so!
- This includes altering operating system settings not exposed through the user interface or
- Running so-called ‘cleanup’ or ‘security’ or ‘optimizer’ tools other than the ones built-into the operating system.
- If your system has general stability issues investigate those first. Unity will tax your system more than most software, including games.
- The Unity Editor is both a game engine and a complex editing application so you’re more likely to experience issues than with any software that is only one of those things.
Unity Hub Install Issues
Quite commonly install fails “validation” or other install failures. You may want to try these troubleshooting steps:
- Verify the “general tips” above are satisfied / followed
- Quit the Unity Hub (check system tray icon!)
- Locate the system’s
TEMPfolder and delete all temporary download folders named similar to:/unityhub-{randomly generated numbers and letters}/
- Ensure Hub and Editor are installed to default locations (eg Program Files)
- (Advanced) Verify the target install location has correct file/folder read/write/execute permissions - particularly if choosing non-default locations
- Do NOT (!!) run the Hub installer, the Hub itself or the Unity Editor with Administrator privileges!
- You often find this advice on the net but this advice is negligent, dangerous and leads to even more issues!
If only a specific module fails to install you may want to uncheck it before installing. Particularly documentation tends to fail but all documentation is found online, where it’s also easier to access (unless you have no / slow / metered internet).
Package Manager Install Issues
Any time you have a package installation error, either because the installation failed or because you get compile errors in package code after installing:
- remove the package where errors originate from
- reinstall that package (if you need it)
If this doesn’t fix the issue then:
- close the project
- delete the package cache
- open the project again
Inexplicable or intermittent issues
The editor maintains a “cache” of converted / optimized assets and build artifacts. From time to time clearing this cache can fix intermittent issues.
When exactly this helps is something you have to acquire a gut feeling for, and more often than not it won’t fix an issue. It will also take a long time to re-open the project due to Unity restoring the cache.
Nevertheless, clearing these files is known to fix some of the nastier issues, particularly the ones that no one can explain or help you with.
- Close your project.
- Open the project folder.
- Delete the following folders and files that exist:
Library(that’s the most important one)TempObjLogs*.csproj(in project’s root folder)*.sln(in project’s root folder)
- Important: Wait for all delete operation(s) to complete!
- Re-open the project (grab a coffee / walk the dog / play a game / etc)