Unity Build Fails or Won’t Run: Fix Guide
This guide helps you diagnose and fix Unity projects that fail to build or run. You’ll learn a systematic approach to identify common issues, from console errors to missing references, and apply practical fixes to get your game compiling and launching again.
What You’ll Need
- A Unity project that currently fails to build or run.
- Unity Editor (any recent version; steps are similar across 2019–2023 LTS).
- Access to the project folder on your computer.
- Optional: a code editor (VS Code, Rider, or Visual Studio) for script inspection.
Step-by-Step
- Read the Console errors. Open the Console window (Window > General > Console). Click each error to see the full message and the script/object it references. Note the first error—often the root cause; later errors are often cascading.
- Fix script compilation errors. If there are red script errors, double-click one to open the script in your code editor. Look for missing semicolons, mismatched braces, or incorrect variable types. Fix the first error, then recompile (Unity auto-recompiles when you return to the Editor). Repeat until the Console shows no script errors.
- Check for missing references. In the Inspector, look for any component with “Missing (Mono Script)� or a red warning icon. Select the GameObject and remove the missing script component (right-click > Remove Component). Re-add the correct script if needed.
- Verify all assets are imported. In the Project window, right-click the Assets folder and select “Reimport All�. This forces Unity to re-import textures, models, and audio, fixing corrupted or outdated imports.
- Clear the Library folder. Close Unity. Delete the “Library� folder in your project root (it will be regenerated). Reopen the project—this resolves many stale cache issues.
- Test a minimal build. Create a new empty scene (File > New Scene), add a simple Cube, and try building that scene alone (File > Build Settings > Add Open Scenes). If it builds, the issue is in your original scene—likely a broken asset or script.
- Check build target settings. In Build Settings, confirm the target platform is correct (PC, Mac, Android, etc.). Ensure you have the required modules installed (e.g., Android Build Support). Try switching to a different platform and back to refresh settings.
- Look for missing shaders or assets. If the build succeeds but the game shows pink or black, you have missing shaders. Reimport the shader, or check that all materials reference valid shaders.
- Run in the Editor first. Press Play in the Editor. If it runs there, the issue is build-specific (e.g., missing scene in build, or stripping). If it doesn’t run in the Editor, fix the runtime error shown in Console.
- Check for infinite loops or null references at runtime. If the game freezes or crashes on launch, look for scripts that reference objects not yet initialized. Use Debug.Log to trace execution, or check for a NullReferenceException in the Console.
Common Mistakes
- Ignoring the first error and fixing later ones—always start at the top of the error list.
- Deleting the Library folder while Unity is open—always close Unity first.
- Forgetting to add the current scene to the Build Settings list—the game will build but run an empty scene.
- Using platform-specific APIs (like iOS) when building for Windows—guard with #if UNITY_IOS.
- Not checking the Console after a failed build—the error may be a warning that becomes an error at build time.
Tips
- Keep your project organized: use folders for scripts, scenes, and assets to quickly locate problems.
- Use version control (like Git) to revert changes if a recent edit broke the build.
- Enable “Auto Refresh� in Edit > Preferences to catch script errors immediately.
- For runtime crashes, check the Player.log file (Windows: %USERPROFILE%\AppData\LocalLow\CompanyName\ProductName\Player.log).
- If the build is too large, check for unused assets and remove them to reduce build time and errors.
Troubleshooting
If the above steps don’t resolve the issue, try these additional checks:
- Build fails with “error CS####�: This is a C# compiler error. Read the full message; it will point to a specific file and line. Fix the syntax or logic error.
- Game runs in Editor but not in build: Check that all scenes you need are in Build Settings. Also, ensure any assets loaded via Resources folder are included—Resources.Load only works if the asset is in a folder named “Resources�.
- Game crashes on launch: Check the Player.log for a stack trace. Often it’s a missing native plugin or a script that assumes a certain platform. Try building with “Scripting Backendâ€� set to Mono instead of IL2CPP (Edit > Project Settings > Player > Other Settings) to see if that helps.
- Build succeeds but game shows black screen: This often means the camera is not rendering. Check that you have a camera in the scene, and that its culling mask includes the layers of your objects.
- Errors about “The type or namespace name ‘X’ could not be foundâ€�: This usually means a missing using statement or a missing assembly reference. Add the correct using at the top of the script, or add the assembly in Project Settings > Player > Other Settings > Scripting Define Symbols.
Frequently Asked Questions
Why does Unity build fail with no errors in the Console?
Sometimes errors only appear when you click “Build�. Check the Build Report window (Window > General > Build Report) for detailed errors. Also, try closing and reopening Unity, as the Editor can sometimes get stuck.
How do I fix a missing script reference?
Select the GameObject, find the missing script component (it will show “Missing (Mono Script)�), right-click it and choose “Remove Component�. Then add the correct script from the Add Component menu.
Why does my game run in the Editor but not in a standalone build?
Common causes: missing scenes in Build Settings, use of Editor-only code (e.g., #if UNITY_EDITOR), or assets not included in the build. Check Build Settings and ensure all needed scenes are listed.
What does “Library could not be found� mean?
This happens when the Library folder is deleted or corrupted. Close Unity and delete the Library folder again, then reopen the project. Unity will recreate it.
Can I build without fixing all warnings?
Warnings are usually fine, but some warnings (like obsolete API usage) can become errors in future Unity versions. It’s best to fix warnings related to your code, especially if they mention “obsoleteâ€�.
How do I check the Player.log file?
On Windows, go to %USERPROFILE%\AppData\LocalLow\CompanyName\ProductName\Player.log. On Mac, it’s ~/Library/Logs/CompanyName/ProductName/Player.log. Open it in a text editor to see runtime errors.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.