Troubleshooting

This section provides information on the following issues:

• Error messages in the Package Manager window
• Missing MonoBehaviour errors
• Package Manager missing or window doesn’t open
• Problems after upgrading Unity to new version
• Package installation fails
• Packages not recognized
• Loading error for hostfxr.dll on Windows
• Resetting your project’s package configuration
• Authentication issues with Git URLs

You can also run the Unity Package Manager Diagnostics tool if you are experiencing problems that might be network-related. For more information, see Network issues.

Error messages in the Package Manager window

The Package Manager displays error indicators in the Package Manager window when it encounters problems:

• System-wide issues

  Error messages that appear in the status bar indicate the Package Manager has detected an issue that is not related to a specific package. For example, if the Package Manager cannot access the package registry server, it displays this message in the status bar:

  

  If your network cannot reach the package registry server, it is probably because there is a connection problem with the network. When you or your system administrator fix the network error, the status bar clears.

  If your network connection is working, but you are not signed into your Unity account, the Package Manager doesn’t display any Asset StoreA growing library of free and commercial assets created by Unity and members of the community. Offers a wide variety of assets, from textures, models and animations to whole project examples, tutorials and Editor extensions. More info
  See in Glossary packages. When you try to use the My Assets scope, the Package Manager displays an error in the status bar:

  

  Click the Sign in button inside the list view to sign into your Unity account through the Unity Hub.

• Package-specific issues

  If a specific package has a problem when loading or installing (for example, when determining which package versions to load), the error icon () appears in the package list next to the compromised package (A). To find out what the problem is, open the compromised package’s details view to see the detailed error message (B):

  

Missing MonoBehaviour errors

While building, if there are a lot of errors about Missing Behavior, the UnityLinker might be mistakenly stripping out a component that it thinks is unreferenced. It often does this because the stripping level is too aggressive. For example, if you have a prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
See in Glossary in an AssetBundle that references the SpriteShape component in the 2D SpriteShape package, the object might be missing and might generate compiler warnings.

To fix this, you can either lower the stripping level for the UnityLinker or declare the package’s assemblies inside the link.xml file in order to preserve them from being stripped:

<linker>
    <assembly fullname="Unity.2D.SpriteShape.Runtime" preserve="all"/>
    <assembly fullname="Unity.2D.Common.Runtime" preserve="all"/>
 </linker>

For more information on stripping levels and the UnityLinker, see Managed code stripping.

Package Manager missing or window doesn’t open

If your package.manifest file is malformed, an error similar to this appears in your Unity console:

Failed to resolve packages: The file [<project-path>/Packages/manifest.json] is not valid JSON:
  Unexpected token '}' at 44:1
  }

You can use the information contained in the error message to fix the JSON. There are a number of online validators that you can use to try to correct the problem. Once you save the corrected file, Unity reloads the Package Manager window.

As of 2019.3, your manifest.json file should not contain any references to the com.unity.package-manager-ui package. You can either reset your project’s package configuration or remove the following line from the manifest’s dependencies list:

    "com.unity.package-manager-ui": "2.1.1",

If you are still experiencing problems, check to see if your project manifestEach Unity project has a project manifest, which acts as an entry point for the Package Manager. This file must be available in the <project>/Packages directory. The Package Manager uses it to configure many things, including a list of dependencies for that project, as well as any package repository to query for packages. More info
See in Glossary uses “exclude” as a package version. This is an obsolete value for the dependencies
See in Glossary property. If you find any lines like these, remove the entire line. Package Manager only installs packages that are explicitly included as a dependency in your project, so once you remove that entry, Package Manager ignores the package and doesn’t install it.

If the Package Manager still fails to load, follow the procedures under Packages not recognized and Resetting your project’s package configuration.

Problems after upgrading Unity to new version

When you upgrade a project to a newer Unity version, the Package Manager automatically updates incompatible packages to newer compatible versions. However, if your package doesn’t compile, the Package Manager displays error messages in the Console.

To correct these messages, read the error messages and fix any problems you can. For example, a package might be missing a dependency on another package or version. In that case, you can try and install the package yourself.

You can also try the following sequence of solutions until you find something that works:

• Back up and then delete the Packages folder under your project.
• Back up and then delete the package sources in your project’s Packages folder, leaving only the manifest.json file. Then try to reload the project.
• Create a new empty project. If the Package Manager window loads successfully, replace the Library/PackageCache/com.unity.package-manager-ui@<version> folder in the failing project with the same folder from the newly created project.
• As a last resort, you can reset your project to the default packageUnity automatically pre-installs a select number of default packages (for example, the Analytics Library, Unity Timeline, etc.) when you create a new project. This differs from a bundled package because you don’t need to install it and it differs from a built-in package because it extends Unity’s features rather than being able to enable or disable them.
  See in Glossary configuration and add back packages one at a time until it works.

Package installation fails

If you are trying to install a new package from the registry and it is not working, it might be due to permission problems.

You must have full permissions on the cache folder:

• Windows: C:\Users\yourname\AppData\Local\Unity\cache
• MacOS: ~/Users/Library/Unity/cache

It might be a problem with the network. Check your firewall and proxy settings.

Sometimes institutional environments, such as schools, government offices, or network-protected workplaces set up proxy servers to control traffic between the network and the Internet, and use their own server certificates which are not recognized by Unity or the Package Manager. Talk to your network administrator.

Packages not recognized

If you see a lot of compilation errors, this might indicate that Unity is not recognizing the packages in your existing project. In this case, you might be missing a .NET component.

For Windows:

1. Download and install Visual Studio 2017 version 15.9.0 or higher with the .NET Core cross-platform development workload selected under Other Toolsets.
2. Download and install the .NET SDK v2.2.101 component.

For MacOS:

1. Download and install the .NET SDK v2.2.101 component.

2. Install any recommended updates in Visual Studio

3. Use homebrew to brew and install mono:

     brew update
     brew install mono # optional
     brew upgrade mono
   

4. If necessary, delete the Library/obj/temp folder under your project and restart Unity.

5. If you are still experiencing difficulties, try rebooting your computer as well.

Loading error for hostfxr.dll on Windows

If the Console reports that the hostfxr.dll library was found, but Unity failed to load it from C:\<path_to_app>\hostfxr.dll, you can fix this error on Windows 7 or Windows Server 2008 R2 by installing both KB2999226 and KB2533623 patches.

Resetting your project’s package configuration

If a project has too many package issues, you can reset your project back to the default package configuration for the Editor’s version of Unity. This operation resets all packages in your project. This might not fix the source of the problem, but it can help you figure out what the problem is.

Note: You can’t undo resetting your package configuration, so make sure you back up the manifest.json file first or make sure your project is under source control. You can also take extra precautions by cloning your project and testing out the operation on the clone before proceeding.

To return to the default package configuration, select Reset Packages to defaults from the Help menu.

Resetting a clone of your project

You can also test the return to the default packages before you perform the final change:

1. Clone your project by copy-pasting your project folder and renaming it so that it is easy to find (for example, if your project is called MyProject then you could use something like clone_MyProject).

2. Load your newly cloned project.

3. From the Help menu, select Reset Packages to defaults.

   Depending on the size of your project, this might take a few minutes.

4. Check that it successfully reset the packages. If so, you can perform the operation safely on the original project.

Authentication issues with Git URLs

If you are using the SSH protocol to install a package by Git URL, you might get an authentication error from Git, even if you are running an ssh-agent in the background and your PID environment variables are set properly.

While your script can successfully start the ssh-agent in the background, the exported environment variables are only available to the Bash shell running the script and to any child process it launches from that point on. This is because your script cannot change environment variables from parent processes, unrelated processes, or previously created child processes. And even if the script is located in .bashrc, it only gets executed in Bash shells.

When you launch Unity or the Unity Hub (both in Windows and macOS) by double-clicking the Unity icon or using the Hub, it is not running in a shell, so the script is not executed. This means that the Unity Editor process doesn’t have these variables set, so ultimately the Git process invoked by Unity doesn’t have them either.

To solve this issue, you can either:

• Open a Bash shell first (before opening the Hub) and manually launch the Unity Editor from that shell.
• If you are on Windows, you can use the setx command to permanently set the environment variables in the Windows registry before the Hub process starts. This solution works best if you can ensure that the script runs once on startup and that the Hub does not start with Windows. For example:

  # Expose env variables to native windows
  setx SSH_AGENT_PID "$SSH_AGENT_PID"
  setx SSH_AUTH_SOCK "$SSH_AUTH_SOCK"