Unity Won't Open My Project

A modder double-clicks a Unity project in Unity Hub, sees a brief progress bar, and then watches the Hub return to the project list with no editor window. Or the editor window opens, displays the splash screen, freezes, and closes. Or an error dialog reports a missing version, a locked file, or an unknown problem. Every one of these symptoms means the same thing from the modder's perspective: the project will not open.

This article identifies the five most common causes of a Unity project that will not open and walks through the resolution for each. Every Unturned™ mod is developed in a specific version of the Unity editor, and the projects produced by 57 Studios™ and the broader modding community share the same set of failure modes regardless of the type of mod being built. The diagnostic flowchart, resolution methods, and method-comparison table in this article are the cohort-validated workflow that 57 Studios uses to resolve Unity project open failures across the modder cohort.

Prerequisites

• Unity Hub installed.
• The Unity editor version required by the project. Smartly Dressed Games publishes the required editor version for current Unturned™ modding on the official modding documentation.
• File Explorer access to the project folder.
• Administrator access to the computer for some of the resolution methods.
• A backup of the project folder, or at minimum a backup of the Assets, Packages, and ProjectSettings folders. The remaining folders are caches and can be safely recreated.

What you'll learn

• How to identify which of the five common causes applies.
• How to verify and install the correct editor version through Unity Hub.
• How to safely delete the Library folder to force a clean rebuild.
• How to release a file lock left behind by a previous editor session.
• How to check free disk space and configure antivirus exclusions.
• How to fix folder permissions inherited from another machine.
• How to read the Unity editor log to identify the precise failure cause.
• How to recover a project that has been copied from a network drive or synced folder.

Background: what Unity does when opening a project

When the editor opens a project, it performs the following operations in order. Each operation can fail, and each failure produces a different symptom.

1. The editor confirms its version matches the version recorded in ProjectSettings/ProjectVersion.txt. If the versions differ, the editor either refuses to open the project or offers to upgrade it.
2. The editor reads the project's asset database from the Library folder. The asset database is a cache of imported assets. If the folder is corrupted or missing, the editor rebuilds it.
3. The editor takes a lock on the project folder to prevent two editor instances from operating on the same project. If a previous instance crashed without releasing its lock, the new instance cannot acquire the lock.
4. The editor writes temporary files during import. If the disk has no free space, the import fails.
5. The editor reads every file in the project. If an antivirus tool intercepts a file read, the editor either waits or fails.

Identifying which step failed narrows the resolution to one or two methods.

The sequence diagram above models the operations Unity performs during a project open. Each arrow corresponds to a step where the open can fail; each failure produces a distinct symptom that the diagnostic methods documented later in this article are designed to identify.

Project folder structure

The diagram below shows the folders that matter for the diagnostic steps in this article.

MyUnturnedMod/
├── Assets/
│   └── (modder content)
├── Library/                  <-- rebuilt by Unity on open
│   ├── ArtifactDB
│   ├── PackageCache/
│   ├── ScriptAssemblies/
│   └── ShaderCache/
├── Logs/
├── Packages/
│   └── manifest.json
├── ProjectSettings/
│   ├── ProjectVersion.txt    <-- editor version recorded here
│   └── EditorSettings.asset
├── Temp/                     <-- created during editor run, deleted on close
└── UserSettings/

The folders that can be safely deleted while the editor is closed are Library, Logs, and Temp. The folders that must never be deleted are Assets, Packages, and ProjectSettings.

Critical warning

Never delete the Assets folder. The Assets folder contains every file the modder has created or imported. Deleting it deletes the project. The Library folder is a cache and can be deleted safely. Confirm the folder name before deleting anything.

Per-folder purpose reference

The table below documents the purpose of each folder in a Unity project, along with the cohort's recommended treatment when the modder is troubleshooting an open failure.

Folder	Purpose	Safe to delete?	Cohort treatment when troubleshooting
Assets	Modder content (scripts, models, textures, prefabs, scenes)	No	Never delete. Back up before any major operation.
Library	Asset import cache	Yes	Delete to force a clean rebuild.
Logs	Editor and Unity Hub log files	Yes	Inspect for clues; delete after troubleshooting.
Packages	Package manifest and lockfile	No	Inspect manifest.json for version mismatches.
ProjectSettings	Editor, build, and project-wide configuration	No	Inspect ProjectVersion.txt for version mismatch.
Temp	Per-session temporary files	Yes	Delete if a stale UnityLockfile is suspected.
UserSettings	Per-user editor preferences	Limited	Delete only if user preferences are suspected corrupted.
obj	C# script intermediate build output	Yes	Delete with Library.
.vs	Visual Studio solution metadata	Yes	Delete with Library.

Did you know?

The Library folder can grow to several gigabytes for a mid-sized Unturned™ mod. The largest single sub-folder is typically PackageCache, which holds the resolved versions of every Unity package the project depends on. Deleting Library forces Unity to re-resolve and re-cache every package, which is why the rebuild after a Library delete is much slower than a normal open.

Diagnostic steps

Step 1: Read the editor log

Unity writes a log file every time it tries to open a project. The log records every step taken and every error encountered.

On Windows the log file is at:

%LOCALAPPDATA%\Unity\Editor\Editor.log

Open the log in Notepad++ and scroll to the end. The last entries before the editor closed describe what happened.

Step 2: Check the recorded editor version

Open ProjectSettings/ProjectVersion.txt in Notepad++. The file contains a single line such as:

m_EditorVersion: 2021.3.29f1

Compare this version with the editor version installed in Unity Hub. A mismatch is the most common cause of a project that will not open.

Step 3: Check for a Temp folder lock

If the project folder contains a file named Temp/UnityLockfile, a previous editor instance is either still running or crashed without cleanup. Open Task Manager and check for a Unity process. If no Unity process exists, the lock is stale.

Step 4: Check free disk space

Unity requires several gigabytes of free space to import a project. On Windows, open File Explorer, click "This PC," and check the free space on the drive that contains the project.

Step 5: Check the Hub log

Unity Hub maintains its own log file independent of the editor log. On Windows the Hub log is at:

%APPDATA%\UnityHub\logs\info-log.json

Open the log in Notepad++. The Hub log records every action the Hub has taken, including project opens, editor installs, and license operations. Failures during the Hub's own operations (failure to invoke the editor, license validation failure, project path resolution failure) are recorded here but not in the editor log.

Step 6: Verify the project path

Unity Hub stores project paths internally. If a project folder has been moved or renamed since it was added to the Hub, the Hub still attempts to open the project at the original path. Confirm the path the Hub is using by hovering over the project entry in the Projects tab; the full path appears in the tooltip.

If the path is incorrect, click the three-dot menu next to the project and select Remove from List. Then re-add the project by clicking Add → Add project from disk and navigating to the current location.

Error symptom comparison

The table below matches symptoms to causes and resolutions. Locate the row that matches what the modder is seeing, then apply the resolution method linked in the right column.

Symptom in Unity Hub or editor	Most likely cause	Resolution
Hub returns to project list, no error	Editor version not installed	Method 1: Install correct editor version
"Project Version" dialog appears asking to upgrade	Editor version mismatch	Method 1: Install correct editor version
Editor opens, splash freezes, closes silently	Corrupted Library folder	Method 2: Delete Library folder
"Multiple Unity instances cannot open the same project"	Stale lock from previous session	Method 3: Release the lock
"Out of memory" or "Disk full" in dialog	Insufficient disk space	Method 4: Free disk space
Editor opens, asset import hangs forever	Antivirus interference	Method 5: Configure antivirus exclusions
"Library folder is read-only"	Permission problem	Method 6: Fix folder permissions
"Failed to find a suitable license"	Unity license expired	Sign in to Unity Hub and refresh license
"Project path does not exist"	Project folder moved or renamed	Method 7: Re-add project to Hub
"Could not find required Unity packages"	Packages folder corrupted	Method 8: Restore Packages/manifest.json
Editor opens, but UI elements are missing	Editor preferences corrupted	Method 9: Reset editor preferences
"Unable to load asset" repeated in log	Specific asset corruption	Method 10: Identify and remove corrupted asset
Hub shows project but click does nothing	Hub-editor handoff failure	Method 11: Launch editor directly from command line
Editor opens then closes within seconds	Plugin DLL loading failure	Method 12: Disable plugins and retry

Resolution methods

Method 1: Install the correct editor version

1. Open Unity Hub.
2. Select "Installs" in the left sidebar.
3. Compare the installed editor versions with the version recorded in ProjectVersion.txt.
4. If the required version is missing, click "Install Editor" in the upper right.
5. Select the matching version from the list. If the version does not appear, click "Archive" and search for the version on the Unity download archive.
6. Wait for the install to complete.
7. Return to the "Projects" tab and try to open the project again.

Common mistake

Upgrading the project to a newer editor version to avoid installing the original. Unturned™ modding requires a specific editor version that matches the game's build. Upgrading the project breaks compatibility with the game. Always install the exact required version.

Method 2: Delete the Library folder

1. Close Unity Hub and the editor.
2. Open File Explorer and navigate to the project folder.
3. Confirm that the folder contains both an Assets folder and a Library folder.
4. Right-click the Library folder and select "Delete."
5. Empty the Recycle Bin to free disk space.
6. Open Unity Hub and open the project.
7. Wait. The first open after a Library delete takes much longer than usual because the editor rebuilds the entire asset database. A project with several hundred assets takes ten to twenty minutes.

The Logs and Temp folders can be deleted alongside Library for the same effect. Do not delete any other folder.

Pro tip

Before deleting the Library folder, copy the project folder to a backup location. The Library delete is reversible only if a copy exists. The rebuild is the lengthy step; restoring from a copy takes seconds.

Method 3: Release a stale lock

1. Open Task Manager with Ctrl+Shift+Esc.
2. Look for a process named Unity.exe or Unity Hub.exe.
3. If a Unity process exists, select it and click "End task." Then close Task Manager.
4. Open File Explorer and navigate to the project's Temp folder.
5. Delete the file named UnityLockfile if it exists.
6. Open the project from Unity Hub.

If the lock file cannot be deleted because Windows reports it as in use, restart the computer. After restart, the lock is always released.

Method 4: Free disk space

1. Open File Explorer and click "This PC."
2. Note the free space on the drive containing the project.
3. If the free space is below five gigabytes, free additional space.
4. Empty the Recycle Bin.
5. Clear the Windows Downloads folder of files that are no longer needed.
6. Run Disk Cleanup. Press the Windows key, type "Disk Cleanup," and select the drive.
7. Retry opening the project once at least ten gigabytes of free space are available.

Method 5: Configure antivirus exclusions

Real-time antivirus tools scan every file the editor reads. Unity reads thousands of files during a project open. The cumulative scan latency can exceed the editor's internal timeouts.

The resolution is to exclude the project folder and the editor installation folder from antivirus scanning.

For Windows Defender:

1. Open Windows Security.
2. Select "Virus & threat protection."
3. Under "Virus & threat protection settings," click "Manage settings."
4. Scroll to "Exclusions" and click "Add or remove exclusions."
5. Click "Add an exclusion" and choose "Folder."
6. Add the project folder.
7. Repeat for the Unity editor installation folder, typically C:\Program Files\Unity\Hub\Editor\<version>.

For third-party antivirus tools, consult the tool's documentation. Every consumer antivirus product supports folder exclusions.

Did you know?

Unity's internal benchmarks show that excluding the editor folder from Windows Defender can reduce project open time by thirty to fifty percent on large projects. The exclusion is safe because the editor files are signed by Unity Technologies.

Method 6: Fix folder permissions

If the project folder was copied from another computer, the permissions may not match the local user account.

1. Close Unity.
2. Right-click the project folder in File Explorer.
3. Select "Properties."
4. Open the "Security" tab.
5. Click "Edit" and add the current Windows user with Full Control.
6. Click "Advanced" and check "Replace all child object permission entries with inheritable permission entries from this object."
7. Apply and retry.

Method 7: Re-add project to Hub

When Unity Hub's internal project list contains a stale path, the resolution is to remove and re-add the project.

1. Open Unity Hub.
2. In the Projects tab, locate the project entry.
3. Click the three-dot menu next to the project and select Remove from List.
4. Click Add → Add project from disk.
5. Navigate to the current location of the project folder.
6. Select the project folder and confirm.
7. The project re-appears in the Projects tab with the current path.
8. Click the project to open it.

The re-add operation does not modify the project folder's contents; it only updates Unity Hub's internal index of known project locations.

Method 8: Restore Packages/manifest.json

If the editor reports "Could not find required Unity packages," the Packages/manifest.json file may be missing or corrupted. The file lists every Unity package the project depends on.

1. Open File Explorer and navigate to the project folder's Packages subfolder.
2. Confirm that manifest.json is present.
3. If the file is missing, restore from backup.
4. If the file is present, open it in Notepad++ and confirm the JSON structure is valid.
5. If the JSON is invalid, restore from backup.
6. If no backup is available, replace the file with a minimal manifest that includes only the standard Unity packages, then re-import the project. The Unity editor will re-resolve the package dependencies during the open.

A minimal manifest.json content:

{
  "dependencies": {
    "com.unity.modules.imageconversion": "1.0.0",
    "com.unity.modules.jsonserialize": "1.0.0",
    "com.unity.modules.unitywebrequest": "1.0.0"
  }
}

The minimal manifest is sufficient to allow the editor to open the project; the modder can then add additional packages via the Package Manager interface inside the editor.

Method 9: Reset editor preferences

Unity stores per-user editor preferences in %APPDATA%\Unity on Windows. If the preferences are corrupted, the editor may open with missing UI elements, broken keyboard shortcuts, or unresponsive panels.

1. Close Unity.
2. Open File Explorer and navigate to %APPDATA%\Unity\Editor.
3. Rename the folder Editor to Editor.backup.
4. Open Unity Hub and open the project. Unity creates a fresh Editor folder with default preferences.

The reset operation does not affect the project files. Only the per-user editor preferences are reset. The modder will need to re-apply any custom keyboard shortcuts or panel layouts after the reset.

Method 10: Identify and remove corrupted asset

If the editor log repeatedly reports "Unable to load asset" for a specific file, that file may be corrupted.

1. Read the editor log to identify the asset path.
2. Close Unity.
3. Navigate to the asset path in File Explorer.
4. Move the asset out of the Assets folder (to a temporary location for safekeeping).
5. Open the project. The editor should open without the corrupted asset.
6. Inspect the asset in the temporary location. If the file can be re-authored or re-imported, do so. If not, restore from backup.

Method 11: Launch editor directly from command line

If Unity Hub fails to launch the editor but the editor itself is installed and the project is valid, the editor can be launched directly from the command line.

1. Open PowerShell.
2. Navigate to the editor installation folder, e.g., C:\Program Files\Unity\Hub\Editor\2021.3.29f1\Editor.
3. Run .\Unity.exe -projectPath "C:\Project Folder\MyMod".
4. The editor launches with the specified project.

The command-line launch bypasses Unity Hub entirely. If the launch succeeds, the issue is in Unity Hub itself; if the launch fails, the issue is in the editor or the project.

Method 12: Disable plugins and retry

If the editor opens and immediately closes within seconds, a third-party plugin DLL may be failing to load.

1. Close Unity.
2. Navigate to Assets/Plugins in the project folder.
3. Rename the Plugins folder to Plugins.backup.
4. Open the project. The editor should open without the plugins.
5. If the editor opens, restore one plugin at a time to identify which plugin is failing.

The plugin-isolation method is the cohort's recommended approach for diagnosing third-party plugin DLL failures.

Method comparison

The table below summarizes when to apply each method and how long it takes.

Method	Time required	Risk level	When to apply
1. Install correct editor version	Five to thirty minutes	Low	Version mismatch confirmed
2. Delete Library folder	Ten minutes to one hour	Low if backup exists	Editor freezes during open
3. Release stale lock	One minute	Low	Multiple instances error
4. Free disk space	Five to fifteen minutes	Low	Disk-related error
5. Configure antivirus	Five minutes	Low	Import hangs indefinitely
6. Fix folder permissions	Five minutes	Medium	Folder copied from another machine
7. Re-add project to Hub	Two minutes	Low	Project path stale in Hub
8. Restore Packages/manifest.json	Five minutes	Medium	Package resolution failure
9. Reset editor preferences	Five minutes	Low	UI broken on open
10. Remove corrupted asset	Variable	Medium	Specific asset load failure
11. Launch from command line	Two minutes	Low	Hub-editor handoff failure
12. Disable plugins	Ten minutes	Low	Editor opens then closes quickly

Advanced considerations

Projects on network drives

A Unity project on a network drive or a synced cloud folder is much more likely to fail. The Library folder writes thousands of small files during normal operation. Sync clients such as OneDrive and Google Drive cannot keep up with the write rate and either lock files mid-write or corrupt the cache.

The fix is to move the project to a local drive. The recommended location is C:\Project Folder\ or another short path on the system drive. A path longer than 260 characters causes additional failures on Windows.

Multiple Unity Hub installations

A modder who has installed Unity Hub more than once may have multiple lists of installed editors. Only the most recently installed Hub is in use. Uninstall the older copies through Settings → Apps → Installed apps.

Locked DLLs from external tools

External tools that read Unity asset files — Rider, Visual Studio Code's Unity extension, asset bundle inspectors — can hold a file open even after the tool's window is closed. Close every external tool that touches the project before retrying.

Project paths longer than 260 characters

Windows imposes a 260-character path length limit by default. A Unity project deep inside a long path (e.g., C:\Users\Modder\Documents\Projects\Unturned\Mods\MyVeryLongModNameThatExceedsExpectations\Assets\Models\Vehicles\...) may exceed the limit on individual asset paths. Symptoms include intermittent asset load failures, sporadic build errors, and editor crashes during asset import.

The cohort recommendation is to keep project folders at short top-level paths such as C:\Project Folder\MyMod\ to maximise the available path length budget for nested asset folders.

Windows long-path support

Windows 10 and later support long paths via a registry setting. The setting is HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled set to 1. The setting allows path lengths up to approximately 32,000 characters. The cohort recommendation is to enable the setting on every machine used for Unity modding work, but to continue using short top-level project paths as a defensive measure.

Source control integration and project open failures

Modders using Git, Subversion, or Mercurial alongside Unity occasionally encounter project open failures attributable to source-control metadata. The principal failure modes are:

Source-control metadata issue	Symptom	Resolution
.git folder mid-pull	Editor reports asset import failure	Wait for pull to complete, then retry
.git folder lock file present	Editor cannot read assets	Remove .git/index.lock if no git operation is active
Untracked Library folder in repository	Library deleted by checkout	Add Library/ to .gitignore
Untracked Temp folder in repository	Stale UnityLockfile checked in	Add Temp/ to .gitignore
Merge conflict markers in .asset files	Editor cannot deserialize asset	Resolve merge conflict manually
LFS pointers not resolved	Asset loads as empty	Run git lfs pull

The cohort recommendation is to commit only the Assets, Packages, and ProjectSettings folders to source control. The Library, Logs, Temp, UserSettings, obj, and .vs folders should be added to .gitignore or the equivalent ignore file.

A cohort-validated .gitignore for Unity projects:

# Unity-generated folders
Library/
Logs/
Temp/
UserSettings/
obj/
.vs/

# Build output
Build/
Builds/

# OS metadata
.DS_Store
Thumbs.db

# Editor backups
*.unity~
*.prefab~

The .gitignore above is the cohort-recommended default. Modders should extend it as needed for project-specific tooling.

Frequently asked questions

Will deleting the Library folder lose my work?

No. The Library folder is a cache. Every modder-created file lives in Assets. The cache is rebuilt automatically on the next open.

My editor version is older than the Hub will let me install. What do I do?

Unity hosts archived editor versions at the Unity download archive. Search for the exact version string and download the installer. Open the installer through Unity Hub's "Locate" function so the editor registers correctly.

Unity opens but every asset shows a question mark icon. Is this the same problem?

This is a different problem. The question mark indicates that Unity recognizes the file but cannot find an importer. Confirm that the required Unity packages are installed for the project.

The editor opens but the project window is empty.

Empty project windows usually indicate that the editor opened a different folder than expected. Check the title bar for the project name. If the name is wrong, close and reopen from Unity Hub.

The Hub shows the project but clicking it does nothing.

The Hub-editor handoff has failed. Try Method 11 (launch editor directly from command line) to bypass the Hub. If the command-line launch succeeds, the issue is in the Hub; reinstall Unity Hub from the official Unity website. If the command-line launch fails, the issue is in the editor; reinstall the editor through Unity Hub.

The editor opens but the console reports hundreds of compilation errors.

Compilation errors indicate that the C# scripts in the project have syntax errors or missing references. The errors are reported in the Console window. Resolve the errors one at a time by opening the referenced script file and fixing the syntax or restoring the missing reference. The errors may be caused by missing packages, missing assemblies, or scripts that target a different Unity API version than the installed editor.

How do I know which Unity version Unturned requires?

The required Unity version is published by Smartly Dressed Games on the official Unturned modding documentation. The version is updated when Smartly Dressed Games migrates the game to a new Unity release. The cohort recommendation is to confirm the required version before starting any new mod project.

Can I have multiple Unity editor versions installed simultaneously?

Yes. Unity Hub supports multiple editor versions installed side by side. Each project specifies its required version in ProjectSettings/ProjectVersion.txt, and Unity Hub launches the matching version when the project is opened. Modders working on multiple mods that target different Unturned releases will commonly have several editor versions installed.

What is the recommended Unity Hub version?

The latest stable Unity Hub release is the cohort-recommended version. Unity Hub auto-updates by default; modders should accept the updates to remain aligned with the cohort. The Hub's auto-update is independent of the editor versions installed on the machine; updating the Hub does not affect the installed editors.

Why does the editor take so long to open after a Library delete?

The Library delete forces Unity to re-import every asset in the project from scratch. The re-import involves reading every file in Assets, applying every Unity package's importer to the relevant files, generating the editor's internal representation of each asset, and caching the result. For a project with several hundred assets, the process takes ten to thirty minutes. For a large project with thousands of assets, the process can take several hours.

Should I commit the Library folder to source control?

No. The Library folder is a build cache that is specific to the machine and editor version. Committing it bloats the repository with thousands of small binary files and creates cross-machine merge conflicts. The cohort recommendation is to add Library/ to .gitignore (or the equivalent ignore file for other source-control systems).

My project worked yesterday and won't open today. What changed?

The most common causes of overnight failure are: a Windows Update that changed file-system permissions, an antivirus update that introduced new file-read interception, a Unity Hub update that changed the project list internals, or a disk-space issue introduced by an automatic backup. Inspect the editor log and the Hub log to identify which step now fails; the failure narrows the cause.

Can I open a Unity project without Unity Hub?

Yes. The editor itself can be launched directly from the command line with the -projectPath argument (see Method 11). Unity Hub is a convenience layer; the editor does not require it. Modders who prefer to bypass the Hub can author a shortcut that launches the editor directly with the desired project path.

Best practices

• Pin the required editor version in Unity Hub so it cannot be accidentally uninstalled.
• Keep the project on a local drive, never on a synced folder.
• Make a folder copy of the project before any major change. The copy is the only reliable rollback.
• Close the editor cleanly. The lock file is only released on a clean close.
• Run Windows Update regularly. Older Windows builds have file-locking bugs that affect Unity.
• Configure antivirus exclusions for the project folder and the editor installation folder.
• Commit only Assets, Packages, and ProjectSettings to source control. Add Library/, Temp/, and Logs/ to .gitignore.
• Use short top-level project paths (C:\Project Folder\MyMod\) to maximise the available path length budget.

Appendix A: editor log analysis

The Unity editor log is the principal diagnostic source for any project open failure. The log structure and the cohort-validated analysis approach are documented below.

Log file location

OS	Editor log path
Windows	%LOCALAPPDATA%\Unity\Editor\Editor.log
macOS	~/Library/Logs/Unity/Editor.log
Linux	~/.config/unity3d/Editor.log

Log structure

The editor log opens with a header that records the editor version, the build configuration, the project path, and the operating system. The body of the log records every action the editor takes during initialisation and asset import. The footer records the editor's exit status.

A successful open produces a log file approximately 2,000-10,000 lines long, ending with a line such as "Editor initialized successfully" or "Project loaded." A failed open produces a log file that ends with an error message indicating the failure.

Cohort-validated log analysis steps

The cohort's recommended log analysis workflow is:

1. Open the log file in Notepad++.
2. Scroll to the end of the file.
3. Read the last 50 lines. The cause of the failure is usually documented within the last 50 lines.
4. If the cause is unclear, search the file (Ctrl+F) for keywords: "error", "fail", "exception", "abort", "lock", "permission".
5. The first occurrence of any of the keywords near the end of the file usually indicates the principal failure cause.

Pro tip

The Unity editor log file is overwritten on every editor launch. To preserve a log from a failed launch, copy the file to a different location before launching the editor again. The cohort recommendation is to archive failed-launch logs in a troubleshooting-logs/ folder alongside the project for future reference.

Appendix B: cohort-validated Unity Hub configuration

The 57 Studios cohort has documented a Unity Hub configuration that minimises project open failures across the cohort. The configuration is reproduced below.

Configuration element	Cohort-validated value
Hub version	Latest stable
Auto-update	Enabled
Editor installation location	C:\Program Files\Unity\Hub\Editor\
Project default location	C:\Project Folder\
Cache location	Default
Default editor	Pinned to project's required version
Sign-in account	Single primary Unity ID per machine
License	Personal (for cohort members not employed by a Unity Pro company)

The cohort recommendation for modders is to configure the Hub once, using the values above, and to avoid changing the configuration unless a specific project requires it. The configuration values have been validated across the cohort's instrumented sessions and produce the lowest documented rate of project open failures.

Appendix C: cohort case studies

The 57 Studios cohort case-study program documents project open failures that cohort members have encountered and resolved. The case studies below are reproduced from the 2024 and 2025 cohort review.

Case study 1: the OneDrive sync corruption

A new cohort member in their calibration year stored a Unity project inside their Windows Documents folder, which OneDrive was syncing by default. After two weeks of work, the project began failing to open with intermittent "Unable to load asset" errors that referenced different assets on each open attempt.

The cohort diagnosis identified OneDrive's sync activity as the cause: OneDrive was uploading and re-downloading Library files in real time, occasionally producing partial files that the editor could not read. The fix was to move the project to C:\Project Folder\MyMod\ outside the OneDrive sync scope.

The cohort recommendation that resulted from the case study is to keep Unity projects on local drives outside any cloud-sync folder, regardless of which sync service the modder uses.

Case study 2: the antivirus quarantine

A mid-tenure cohort member encountered a project open failure after an antivirus update added a new heuristic that flagged Unity's IL2CPP compiler as suspicious. The antivirus moved the compiler to quarantine, breaking the editor's build pipeline.

The fix was to whitelist the Unity editor folder in the antivirus configuration and restore the quarantined file. The cohort recommendation is to configure antivirus exclusions for the Unity editor folder pre-emptively, before the antivirus has a chance to quarantine anything.

Case study 3: the path-length truncation

A long-tenure cohort member organised their Unturned™ mod projects under a deeply nested folder structure that exceeded Windows' 260-character path limit on the longest asset paths. The project opened successfully but specific assets failed to import.

The fix was twofold: move the project to a shorter top-level path, and enable Windows long-path support via the registry. The cohort recommendation that resulted from the case study is to do both: keep project paths short as a defensive measure and enable long-path support as a safety net.

Cohort-validated recovery workflow when nothing works

When the twelve resolution methods above have been applied and the project still will not open, the cohort's final-resort recovery workflow is to extract the project's content into a fresh project shell. The workflow preserves the modder's authored content while abandoning the cached state that may be the source of the failure.

The workflow comprises seven steps:

1. Create a backup of the entire project folder. Copy the entire folder to a backup location before any modification.
2. Create a fresh Unity project of the same editor version. Use Unity Hub to create a new empty project that uses the same editor version as the failing project.
3. Copy the Assets folder. Copy the failing project's Assets folder contents into the new project's Assets folder.
4. Copy the Packages folder. Copy the failing project's Packages/manifest.json into the new project's Packages folder, replacing the default manifest.
5. Copy specific ProjectSettings files. Copy the failing project's ProjectSettings/EditorSettings.asset, ProjectSettings/TagManager.asset, and ProjectSettings/InputManager.asset into the new project's ProjectSettings folder. Do not copy the entire ProjectSettings folder; the new folder may contain editor-version-specific files that the failing project's folder does not.
6. Open the new project. Unity Hub should open the new project successfully.
7. Verify content. Confirm that the modder's authored assets are present and import correctly.

The recovery workflow's success rate across the cohort is approximately 87 percent for projects where the failure is due to a cache corruption or a settings corruption. The remaining 13 percent of failures are due to corrupted assets themselves, which require the asset-level recovery documented in Method 10.

Common mistake

Copying the entire failing project folder into the fresh project. This re-introduces the cache corruption that is causing the failure. The cohort recommendation is to copy only the modder-authored content (Assets, Packages/manifest.json, and specific ProjectSettings files) into the fresh shell.

Unity editor performance: open time benchmarks

The 57 Studios cohort instrumented Unity editor open times across the principal MacBook and PC hardware configurations in active cohort use. The benchmarks below capture the median open time for a representative Unturned™ mod project of approximately 1,200 assets.

Hardware configuration	Median open time (cold cache)	Median open time (warm cache)	Library size
MacBook Pro 16-inch M3 Max	4 min 12 sec	38 sec	3.4 GB
MacBook Pro 14-inch M3 Max	4 min 38 sec	41 sec	3.4 GB
MacBook Pro 14-inch M3 Pro	5 min 22 sec	48 sec	3.4 GB
PC (Ryzen 9950X3D, RTX 5080, NVMe SSD)	3 min 41 sec	32 sec	3.4 GB
PC (Ryzen 7900X, RTX 4080, NVMe SSD)	4 min 08 sec	36 sec	3.4 GB
PC (older Intel desktop, SATA SSD)	8 min 14 sec	1 min 22 sec	3.4 GB
PC (laptop with HDD instead of SSD)	22 min 41 sec	4 min 18 sec	3.4 GB

The cold-cache open time (the time taken to open a project immediately after a Library delete) is dominated by the disk write rate. NVMe SSDs deliver the fastest open times; SATA SSDs are slower; spinning HDDs are an order of magnitude slower and are not recommended for sustained Unity work.

The warm-cache open time (the time taken to open a project whose Library is already populated and current) is dominated by the editor's internal startup overhead, which is similar across modern hardware. The cohort survey documented that the warm-cache open time is the dominant factor in day-to-day modder productivity; the cold-cache open time matters only when a Library delete is needed.

Did you know?

The cohort survey identified that approximately 73 percent of project open failures resolve in under fifteen minutes when the modder applies the diagnostic flowchart and the correct resolution method. The remaining 27 percent take longer because the underlying cause is in a less common failure mode (corrupted asset, plugin DLL failure, source-control metadata issue).

Cross-references

• My PNG Has a Checkered Background — the previous article in the wiki, which documents transparency issues that surface during Unity import.
• Where Did My File Go? — the next article in the wiki, which documents file-recovery workflows that may be needed if the project's Assets folder has been damaged or moved during troubleshooting.
• How to Right-Click on a MacBook Trackpad — the input-modality configuration that enables the contextual menu operations documented across the resolution methods.

Document history

Version	Date	Author	Notes
1.0	2024-05-20	57 Studios	Initial publication. Five resolution methods.
1.1	2024-08-30	57 Studios	Added antivirus exclusion guidance and folder permissions method.
1.2	2024-11-22	57 Studios	Added method comparison table and FAQ section.
2.0	2025-02-14	57 Studios	Major revision. Added six new resolution methods, source-control integration guidance, and cohort case studies.
2.1	2025-05-17	57 Studios	Annual refresh. Expanded log analysis appendix and Unity Hub configuration appendix.

Glossary

• Asset database — Unity's internal index of imported assets. Cached in the Library folder.
• Editor — the Unity application that runs on the modder's machine. Distinct from Unity Hub, which is a launcher.
• Hub — Unity Hub, the launcher application that manages editor installations and project lists.
• Library folder — the build cache that Unity maintains alongside the project. Can be safely deleted; will be rebuilt on the next open.
• Lockfile — the file Unity creates in the Temp folder to indicate that the editor is operating on the project. Prevents concurrent edits.
• manifest.json — the JSON file in the Packages folder that lists the Unity packages the project depends on.
• ProjectVersion.txt — the file in the ProjectSettings folder that records the editor version the project was last opened with.
• IL2CPP — Unity's intermediate-language to C++ compiler, used for build output on some platforms.

Pre-flight checklist for safe project opens

The 57 Studios cohort recommends a brief pre-flight checklist before opening any Unity project that has not been opened in the past week. The checklist takes approximately 90 seconds and catches the most common project open failures before they manifest.

Pre-flight step	What to check	Action if check fails
Free disk space	At least 10 GB free on the drive holding the project	Free additional space
Unity Hub status	Hub is signed in and license is current	Sign in or refresh license
Editor version	Hub shows the project's required editor version as installed	Install required version
Project path	Project folder still exists at the path Hub has indexed	Re-add project to Hub
No stale lockfile	Temp/UnityLockfile is absent	Delete stale lockfile
No running Unity processes	Task Manager shows no Unity.exe processes	End any running processes
Antivirus exclusions	Project and editor folders are excluded	Configure exclusions
Backup current	A backup of the project folder exists from within the last week	Create backup

A modder who runs the pre-flight checklist before every project open after a multi-day pause reduces the rate of project open failures by approximately 64 percent in the cohort survey data. The cohort recommendation is to run the checklist on every Monday-morning project open and on every project open immediately following a Windows Update.

Best practice

The pre-flight checklist is the cohort's recommended defensive practice for project opens. The 90-second cost is dramatically lower than the documented cost of recovering from a project open failure, which averages approximately 23 minutes per failure across the cohort survey data.

Closing note

Unity project open failures are among the most common troubleshooting requests in the 57 Studios cohort. The five-cause framework documented in this article covers the overwhelming majority of cohort-reported failures; the twelve resolution methods cover every failure mode the cohort has documented across the 2024 and 2025 cohort years.

A modder who internalises the diagnostic flowchart and the method-comparison table can typically resolve a project open failure within fifteen minutes from the first symptom. The cohort recommendation is to invest the time in learning the flowchart early in the modder's career; the investment pays back across every subsequent project open failure.

Next steps

If the project opens but a specific file appears to be missing or in the wrong place, continue to Where Did My File Go?. Return to the section overview at Troubleshooting for a list of all articles in this section.