This post is a quick summary on how to approach troubleshooting in and around Unity.
Inexplicable Permission Issues or “File not found”
Make sure your Antivirus is configured to have the project’s root folder excluded from Online/Live scans! This will also speed up working in the project, sometimes quite noticably so.
Sometimes permission-based issues are caused by users changing or ignoring the OS’ file system and account permission settings. Be sure to install the Hub/Editor to default locations, and create new projects in default locations (ie Documents).
IMPORTANT: Whatever you do, do NOT run the Unity Hub or Unity Editor with Administrator privileges. Not even when that makes the issue go away since that’s not the root cause! You’re giving a host of developer tools admin privileges that every hacker would love to run on your system unhampered. You can even destroy your OS by accidentally deleting protected files through a script when working with Admin privileges.
Log Files
Be it an issue installing or launching the Hub, the Editor or your Build, there’s a log file for each which you can and should inspect for any errors that do not appear visibly.
Cache and Temp Files
Unity generates a number of temporary files, be it in the project itself or the Package Manager or the Hub downloads. When there is no clear cause for an issue, it’s good practice to delete the associated temp file locations.
IMPORTANT: Close all running Editor instances before deleting temp folders, and wait for the delete operation to complete before re-opening the editor/project!
Project Caches
It may help to delete these folders if you have seemingly random, unexplicable issues or cannot open the project at all.
It is best practice to delete the Project caches when you get new issues after upgrading the project to a new Unity editor version.
The following subfolders in a project can be safely deleted, and should be deleted if you need to restart the project from a clean slate:
- /Library
- /Obj
- /Temp
- /Logs
Package Cache & Downloaded files
Delete the package cache if you have inexplicable compile errors in packages, especially if the issue does not go away after removing and re-importing the package. This may indicate that the cached package may be corrupt.
By deleting the package cache you force the Package Manager to re-download packages. The package cache can also grow quite big over time, tens of gigabytes is not uncommon for heavy users.
Delete the Downloaded files locations if editor installations fail in the Unity Hub.
Note: Both package cache and download locations are also configurable in Unity Hub => Preferences and thus may be system-specific.
Upgrade to latest Versions!
Understandably, large teams try to lock-in to specific editor and package versions. However, this best practice for LARGE TEAMS has somehow trickled down to the solo indie developers and small teams becoming super-hesitant to upgrade versions.
Do not be afraid to upgrade! Especially if you DO have an issue. You can always do so in a copy of the project! There’s always a chance that the issue you are having is known and has since been fixed.
Editor version upgrades
Even if you do not have any issues, it is BEST PRACTICE for small teams to keep updating the editor frequently to the latest patch release. That’s the third number, ie an upgrade from 2022.3.42f1 to 2022.3.45f1.
IMPORTANT: Do NOT stay on early patch releases! You can expect to experience more bugs in earlier patch release versions. I would recommend to keep upgrading until you’re at least past 20f1 and then you may want to upgrade every +10 patch releases at the latest - unless you have absolutely zero issues whatsoever.
CAUTION: downgrading editor versions is NOT supported, and when it has to be done, be sure to delete the Project caches beforehand! There are no guarantees that an editor version downgrade will work flawlessly. It may introduce persistent issues, an in rare cases may even corrupt assets. These are more likely to occur when downgrading between major versions (ie 2022, 2023).
Package version upgrades
Package version updates are unlikely to have been fully tested against all possible dependent package versions. Thus when upgrading one package, it is best to also upgrade any dependent package to their latest versions.
Issues may even suddenly occur to you without changing anything in the project because development of the editor and packages continues. Mainly such packages that have an online or cloud service component are prone to this issue. For instance, recently someone reported a failing Cloud Service API call that used to work, and the fix was to upgrade the Cloud Service package. It can be that simple!
Debug and Profile
Any odd issues like random framerate drops are best analyzed by debugging and profiling.
Ideally try to isolate the issue and reproduce it in a new, empty project. This would tell you whether the issue is with a particular editor version and its packages, or a project-specific issue. All too often it is the latter, while devs are all too quickly to blame it on the former.
In my experience, an editor or runtime performance regression is far, far more commonly caused by the project’s assets themselves than it is by the Unity Editor or Unity Runtime or Unity’s packages.
Be cautious when using editor scripts and assets that are heavy on editor tools. These can have a SEVERE impact on Editor behaviour, sometimes only observed in certain circumstances. Most editor tooling assets are not developed within a real production project, thus they are often ill-prepared to handle the number and size of assets or the workflows of a production project.