Map Loading Failures

Intermediate40-60 minutesWindowsUnturnedUnity Editor

A map author who has completed the editor pipeline and verified that the map loads without errors in the Level Editor may find that the same map fails catastrophically when loaded through the game client. The loading screen stalls at 53 percent. The map returns to the main menu without an error dialog. Textures render as solid white or pink. The game crashes to desktop when the loading bar reaches 90 percent. The dedicated server reports a GUID conflict and terminates the startup sequence. These failure modes are not visible in the editor, and they are the primary reason that experienced map authors spend proportionally more time on validation than on initial map authoring.

This article documents every loading failure mode that the 57 Studios™ cohort has observed across dozens of map publication cycles, organized by symptom with the root cause, the diagnostic procedure, and the validated fix. The article is primarily diagnostic: the centerpiece is the symptom-cause-fix table in the Common Failure Modes section, and the diagnostic workflow in the subsequent section teaches the reader how to identify the root cause of any loading failure from the observable symptom alone. The article also covers the -ValidateAssets output interpretation, GUID collision diagnosis, asset bundle inspection techniques, and the recovery procedures for each failure class.

Prerequisites

• Unturned™ installed and launchable in single-player mode.
• Unturned Dedicated Server tool installed (U3DS) if testing server-side loading.
• A map that loads without errors in the Unturned™ Level Editor but exhibits loading failures when tested through the game client.
• Access to the Client.log file at %LOCALAPPDATA%\Unturned\Logs\Client.log and the Server_[ID].log file in the U3DS installation directory.
• A text editor capable of reading large log files (Notepad++ or equivalent).
• A backup of the map's project folder before beginning any diagnostic or repair procedure.
• PowerShell available for log searching and file inspection commands.
• Familiarity with the map folder structure: Level/, Bundles/, Config.json, and the level .asset file.

What you will learn

• How to identify any map loading failure from its observable symptom using the symptom-cause-fix reference table.
• How to execute the diagnostic workflow that traces any loading failure to its root cause.
• How to run and interpret -ValidateAssets output, including cascade error patterns.
• How to diagnose and resolve GUID collisions between asset versions and across Workshop dependencies.
• How to inspect asset bundles for corruption, missing references, and bundle GUID mismatches.
• How to diagnose missing asset errors and broken prefab references in spawn tables and level configurations.
• How to recover from each loading failure class and re-validate the fix.

Background: how Unturned loads a custom map

The Unturned™ engine loads a custom map through a multi-stage pipeline. Each stage can fail independently, and a failure at an earlier stage prevents later stages from executing. Understanding the pipeline structure is the prerequisite to diagnosing loading failures, because the stage at which the failure occurs directly indicates the failure class.

The map loading pipeline

As shown in the flowchart above, the loading pipeline has ten distinct decision points. A map that reaches stage T (server ready) has passed every loading gate. A failure at any gate produces a specific symptom that maps to the failed stage. The following sections document each failure mode with its corresponding gate.

Why the editor bypasses loading validation

The Unturned™ Level Editor loads the map through a different code path than the game client. The editor does not validate the master bundle GUID. It does not run the -ValidateAssets checks. It loads prefabs directly from the Unity project rather than from the exported asset bundle. It does not resolve spawn table entries against the full asset registry. It does not initialize the navmesh system. It does not exercise the network replication path. A map that loads cleanly in the editor has passed approximately 30 percent of the validation gates that the game client enforces. The editor is a development tool, not a test environment.

Diagnostic workflow

The diagnostic workflow below is the cohort-validated procedure for identifying the root cause of any loading failure. The workflow is designed to be executed in sequence, starting from the cheapest diagnostic step (inspecting the client log) and proceeding to more expensive steps (bundle extraction, GUID database inspection) only when the earlier steps do not produce a definitive answer.

Step 1: Capture the failure evidence

1. Launch Unturned™ and select the map from the single-player level list.
2. Observe the loading behavior carefully. Note the exact loading percentage at which the failure occurs, the error message (if any), and whether the failure is consistent across repeated attempts.
3. Open Client.log at %LOCALAPPDATA%\Unturned\Logs\Client.log immediately after the failure. The log records every loading event and error message.
4. Search for the following keywords in the log: Error, Failed, Missing, Conflict, Exception, NullReference, GUID, not found, unable to load.
5. If the failure occurs on a dedicated server, open Server_<ID>.log in the U3DS installation directory and repeat the keyword search.

Step 2: Map the symptom to the failure class

Use the symptom-cause-fix table in the Common Failure Modes section to map the observable symptom to the most likely failure class. Each entry in the table includes the specific log message signature that confirms the diagnosis.

Step 3: Apply the class-specific diagnostic

Each failure class in the following sections has a dedicated diagnostic procedure that confirms the root cause and identifies the exact asset or reference that needs repair.

Step 4: Repair and re-validate

Apply the validated fix for the identified failure class, then re-run the loading test. If the failure persists, return to Step 2 and check for cascade failures (a single root cause that produces multiple symptom-class matches).

Step 5: Run full validation

After the map loads successfully, run -ValidateAssets to confirm that the repair did not introduce secondary issues.

Common failure modes: symptom-cause-fix reference table

The table below is the centerpiece diagnostic reference for every loading failure mode the cohort has documented across multiple map publication cycles. The leftmost column is the observable symptom. The center column is the root cause with the log message signature that confirms it. The rightmost column is the validated resolution procedure.

Symptom	Root cause and log signature	Resolution
Map does not appear in the level list	Level .asset file is missing, malformed, or located in the wrong directory. Log: no entry for the map folder name.	Confirm the level .asset file exists at the map root. Confirm the file is not zero bytes. Confirm the map folder is in the correct Maps/ directory.
Map appears in the level list but returns to the main menu when selected	The Bundle field in the level .asset points to a master bundle name that does not exist. Log: Failed to load level bundle or Could not find bundle.	Open the level .asset in Notepad++. Confirm the Bundle field matches the master bundle name in the Bundles/ directory exactly. Correct any mismatch.
Infinite loading screen: progress bar stalls at a specific percentage	A prefab, texture, or spawn table entry references an asset that does not exist in any loaded bundle. Log: Missing asset or Failed to resolve GUID or Unable to load asset.	Identify the missing asset from the log entry. Search the map's prefab references and spawn tables for the missing GUID or path. Remove or replace the reference.
Infinite loading screen: progress bar stalls between 50-70 percent	Spawn table entry references an item ID that is not registered in any loaded mod. Log: Failed to find item or Missing spawn table entry.	Open each spawn table .dat file. Verify every item ID in the table exists in a loaded mod. Remove or correct invalid IDs.
All custom textures render as solid white or pink	Asset bundle is missing from the Bundles/ folder, or the bundle file is corrupt. Log: Bundle not found or Failed to load bundle.	Confirm the bundle .unity3d or .masterbundle file exists in the Bundles/ folder. Rebuild the bundle in Unity Editor if the file is corrupt.
Some custom textures render white while others render correctly	Individual prefabs within the bundle reference textures that were not included in the bundle build. Log: Texture not found in bundle or Missing texture reference.	Rebuild the asset bundle in Unity Editor. Confirm all textures are assigned to the correct bundle in the Unity Asset Bundle panel. Verify all texture dependencies are included.
Game crashes to desktop during the loading screen with no error dialog	An object in the level has a broken mesh filter or mesh renderer. The engine encounters a null mesh reference and cannot recover. Log: NullReferenceException or Mesh is null.	Open the map in the Level Editor. Use the error output to identify the object with the broken mesh. Repair or remove the object. Re-export the level data.
Game crashes when the camera points at a specific angle after loading	Broken occlusion culling configuration. A culling volume or manual culling region is incorrectly configured. Log: Culling group error or Occlusion volume invalid.	Remove or reconfigure the occlusion culling volume in the affected area. Re-bake occlusion data. Test each crash angle.
Game loads but the player falls through the terrain at the spawn point	Spawn point is placed below the terrain surface or on a collider that the engine cannot resolve. Log: no explicit error; observable through gameplay.	Open the map in the Level Editor. Move the spawn point to a clear area on valid terrain surface. Re-export.
Dedicated server fails to start with the map. Console reports loading errors.	A .dat file in the map has a parsing error. Log: Parsing error in followed by the file path.	Open the reported .dat file. Correct the malformed line. Validate the file structure against the spawn table format reference.
Dedicated server starts but reports GUID conflict and terminates	Two asset bundles loaded by the server contain assets with identical GUIDs. Log: GUID conflict between followed by the two asset paths.	Identify both assets that share the GUID. Re-assign a new GUID in Unity Editor for one of them. Rebuild the bundle.
Server starts but custom assets appear as white placeholders	Asset bundle exists on the server but the server's Bundles/ directory does not contain the correct relative path. Log: Failed to load bundle with the bundle path.	Copy the asset bundle files to the server's Bundles/ directory at the correct relative path matching the client installation.
Water renders incorrectly or causes extreme framerate drops	Multiple water volumes have planar reflections enabled. Log: Water reflection count exceeded or no explicit error.	Disable planar reflections on all but one water volume. Re-export the map.
Zombies are present in single-player but absent on the dedicated server	The dedicated server has Workshop items missing. The zombie spawn table references a zombie type from a missing Workshop dependency. Log: Missing zombie asset or Failed to spawn zombie.	Add the missing Workshop dependency to the server's WorkshopDownloadConfig.json. Verify the dependency load order.
Navmesh loads but zombies walk into walls and do not pathfind	The navmesh bake settings (agent radius, height, slope) do not match the map's terrain and object geometry. Log: Navmesh bake incomplete or no explicit error.	Re-bake the navmesh in Unity Editor with agent settings that match the map's walkable surface properties. Test with a simple open area first.
Loading bar reaches 100 percent but the screen remains black	The level's environment lighting configuration is broken. The skybox or light probe data failed to load. Log: Failed to load lighting data or Skybox invalid.	Open the map in the Level Editor. Verify the skybox is assigned correctly. Re-bake light probes. Re-export the level.
Map loads in single-player but crashes when a second player joins	A spawn table entry or object reference breaks under network replication. Log: Network replication error or Failed to replicate entity.	Test each spawn table entry and object reference in a multiplayer environment. Remove any entry that produces replication errors.
Custom item icons do not appear in the inventory	Item icon orthographic camera is not configured in the prefab. Log: Failed to generate icon or Icon camera missing.	Attach an orthographic camera to the item prefab in Unity Editor. Configure the camera for icon generation. Rebuild the bundle.
Text renders as boxes or Unicode replacement characters	The localization file (English.dat) is missing or uses an incorrect encoding. Log: Localization file error or Failed to parse localization.	Confirm English.dat exists in the map folder. Verify the file is saved as UTF-8 without BOM. Correct any malformed entries.
Map loads but all interactable objects (doors, storage, safes) are non-functional	Object interactivity scripts failed to initialize. The object prefab is missing the interactable script component. Log: Interactable component missing or Failed to initialize interactable.	Open the non-functional object in the Level Editor. Verify the prefab has the correct interactable script attached. Rebuild the bundle.
Custom assets load with the correct shape but wrong material	Material references within the prefab point to material names that do not exist in the bundle. Log: Material not found or Shader not found.	Open the prefab in Unity Editor. Verify every material reference points to a material that is included in the bundle build. Rebuild.

ValidateAssets output interpretation

The -ValidateAssets command-line flag performs deep inspection of every asset in the map, including meshes, textures, materials, audio files, and navmesh data. The flag is the single most important quality gate before a map can be considered loading-failure-free, and the Smartly Dressed Games curated maps documentation requires that a map produce zero validation errors before it can be accepted.

How to run -ValidateAssets

1. Create a shortcut to Unturned.exe (default: C:\Program Files (x86)\Steam\steamapps\common\Unturned\Unturned.exe).
2. Append -ValidateAssets to the target field.
3. Launch Unturned™ through the modified shortcut.
4. Load the map in single-player mode. The validation runs during the loading screen.
5. After the map loads, open the Asset Errors menu from the in-game menu, or examine Client.log at %LOCALAPPDATA%\Unturned\Logs\Client.log.

What each validation error means

Validation error	What it tests	Why it fails	Severity
Navmesh Readable	Object navmeshes have the CPU Readable flag enabled in Unity import settings.	The navmesh mesh does not have CPU Readable enabled. The engine cannot read navmesh data from the GPU-only mesh.	Critical. Zombies will not pathfind on this object.
Mesh Readable	Non-navmesh meshes do not have CPU Readable enabled unnecessarily.	A non-navmesh mesh has CPU Readable enabled. This wastes CPU memory.	Low. No gameplay impact but increases memory usage.
Missing Meshes	Mesh filters reference a valid mesh.	The mesh filter component is empty or references a mesh that was not included in the bundle build.	Critical. The object will not render.
Mesh Vertex Counts	Meshes with unusually high vertex counts.	A single mesh exceeds the recommended vertex budget (typically 10,000+ vertices).	Medium. May cause performance degradation on lower-end hardware.
Missing Materials	Renderers have at least one material assigned.	The mesh renderer has an empty material slot.	Critical. The object renders as solid pink or white.
Material Counts	Renderers with excessive material counts.	A single renderer uses more materials than recommended (typically 4+).	Medium. Increases draw calls and degrades performance.
Texture Readable	Textures do not have CPU Readable enabled unnecessarily.	A non-essential texture has CPU Readable enabled.	Low. Wastes memory. Disable where possible.
Texture NPOT	Textures use power-of-two dimensions.	Texture dimensions are not powers of two (e.g., 300x200 instead of 256x128).	Medium. May cause GPU warnings or black textures on lower-end hardware.
Audio Samples	Long audio clips with high sample rates.	An audio clip is excessively long or uses an unnecessarily high sample rate.	Low. Increases bundle size and memory usage.

Cascade error patterns

A single root cause can produce multiple validation errors. The most common cascade patterns are:

Cascade trigger	Errors produced	Resolution
A prefab is missing from the bundle build	Missing Meshes, Missing Materials, Texture NPOT (cascaded from the prefab's children)	Add the missing prefab to the bundle build. Rebuild.
The master bundle GUID changed	Missing Meshes (all prefabs), Missing Materials (all prefabs)	Rebuild the master bundle and re-export the map. Confirm the level .asset references the correct bundle name.
A texture was removed from the bundle but a material still references it	Missing Materials, Texture Readable (cascaded)	Either add the texture back to the bundle or update the material to use a different texture.
An audio clip was imported with incorrect settings	Audio Samples (single clip), then cascade to missing references if the clip was renamed	Re-import the audio clip with correct settings. Update all references.

The cohort recommendation is to fix errors in the order they appear in the validation output, because a single broken reference at the top of the output can cascade into multiple dependent errors later in the output. After fixing all reported errors, re-run -ValidateAssets to confirm the fix succeeded. A map that produces zero validation errors after the fix pass is ready for loading validation testing.

GUID collision diagnosis and resolution

GUID collisions occur when two asset bundles loaded simultaneously contain assets with identical GUIDs. The engine uses GUIDs to resolve prefab references, material references, and texture references. A collision causes the engine to load the wrong asset for one of the references, producing incorrect textures, missing meshes, or loading failures. GUID collisions are especially common when a map depends on multiple Workshop items that were created from a shared Unity project or when a map is updated and the new bundle retains the GUIDs of assets that were removed and re-added.

How to detect a GUID collision

1. Search Client.log or Server_<ID>.log for the keyword GUID conflict.
2. The log entry includes both asset paths that share the conflicting GUID.
3. A GUID collision may also manifest as assets that render with the geometry of one asset and the texture of another. This is the observable symptom of the engine loading the wrong asset for a given GUID.

How to resolve a GUID collision

Collision type	Resolution
Two assets within the same map bundle share a GUID	Open the map's Unity project. Use the GUID search tool to locate both assets. Regenerate the GUID for one asset (delete and re-import, or modify the corresponding Unity resource file). Rebuild the bundle.
Two separate Workshop items that the map depends on share a GUID	Contact the author of one of the Workshop items to request a GUID regeneration. If contact is not possible, remove the dependency on the conflicting Workshop item and replace the affected assets with locally-authored equivalents.
An asset from a previous version of the map conflicts with the current version	Clean the Workshop cache and re-download the map. If the conflict persists, the map's published_file_id.txt linkage file may point to an outdated bundle. Clear the Workshop cache folder for the map and re-subscribe.
A vanilla game asset GUID conflicts with a custom asset GUID	Extremely rare. The vanilla GUID namespace is separate from the custom asset namespace. If a conflict occurs, the custom asset GUID was generated incorrectly. Delete the custom asset's project resource file and re-import it into Unity to regenerate the GUID.

GUID cache clearing procedure

When a GUID conflict is traced to a cached bundle that has not been refreshed:

1. Close Unturned™ completely.
2. Navigate to the Workshop cache folder: %PROGRAMFILES(X86)%\Steam\steamapps\workshop\content\304930\.
3. Locate the workshop item folder for the map by its Workshop ID.
4. Delete the contents of the workshop item folder (not the folder itself).
5. Launch Unturned™. The game re-downloads the map from the Workshop.
6. Test the map loading again.

Missing asset diagnosis and resolution

Missing asset errors occur when a prefab, texture, material, or spawn table entry references an asset that the engine cannot resolve. The engine logs the missing reference in Client.log with the asset path or GUID. The missing asset may be in the map's own bundle, in a bundled dependency, or in a Workshop dependency that is not loaded.

How to identify a missing asset

1. Search Client.log for Missing, not found, unable to load, or Failed to resolve.
2. Each matching entry includes the asset path or GUID that the engine attempted to resolve.
3. The asset path indicates which bundle and which asset within the bundle is missing.

Missing asset resolution table

Missing asset location	Likely cause	Resolution
Asset in the map's own bundle	The prefab or texture was not assigned to the bundle in Unity Editor, or was removed from the bundle before the build.	Open the map's Unity project. Assign the missing asset to the correct bundle. Rebuild the bundle.
Asset in a Workshop dependency	The Workshop dependency is not loaded, or the dependency's version is out of date.	Subscribe to the Workshop dependency. Confirm the dependency's published version includes the referenced asset.
Asset in a spawn table entry	The spawn table references an item ID that does not exist in any loaded mod.	Open the spawn table .dat file. Remove the invalid item ID. Replace with a valid ID or remove the entry.
Asset path in Config.json or level .asset	The path was typed manually and contains a typo.	Open the configuration file. Correct the path to match the actual file structure.
Asset loaded at runtime via a script	The script references an asset that was not loaded before the script executed.	Ensure the asset bundle is loaded before the script runs. Add the bundle to the map's dependency list.

Asset bundle inspection techniques

When a loading failure is traced to an asset bundle that may be corrupt or incomplete, the cohort-validated inspection techniques below help identify the specific issue without requiring a full Unity Editor session.

Technique 1: Bundle file size check

A healthy asset bundle file (.unity3d or .masterbundle) has a file size proportional to the assets it contains. An unexpectedly small bundle (under 1 KB for a bundle that should contain multiple prefabs) indicates a failed or incomplete bundle build. Compare the bundle file size against the size recorded in the previous successful build.

Technique 2: Bundle header inspection

Open the bundle file in a hex editor (HxD or equivalent). The first four bytes of a valid Unity asset bundle are the magic number UnityFS. A file that does not start with UnityFS is not a valid bundle and will fail to load.

Technique 3: Bundle content listing

Use the AssetStudio or UnityBundleExplorer tool to list the contents of a .unity3d bundle file without loading it into Unity. Compare the listed contents against the expected asset list. Missing entries confirm that the bundle build excluded assets that the prefabs reference.

Technique 4: Bundle rebuild procedure

If any inspection technique indicates a corrupt or incomplete bundle, the validated resolution is:

1. Open the map's Unity project.
2. In the Asset Bundle panel, confirm every prefab, texture, and material that the map uses is assigned to the correct bundle.
3. Delete the existing bundle build output from the Bundles/ directory.
4. Rebuild all bundles from Unity Editor.
5. Confirm the new bundle file size is consistent with the expected content volume.
6. Re-run the loading test.

Frequently asked questions

Why does my map load in the editor but not in the game client?

The editor bypasses several validation steps that the game client enforces. The editor does not validate the master bundle GUID. It does not run -ValidateAssets. It loads prefabs directly from the Unity project rather than from the exported asset bundle. It does not resolve spawn table entries against the full asset registry. The editor is a development tool, not a test environment. Any map that loads in the editor but fails in the game client has an issue in one of these untested areas.

How do I tell which loading stage is failing?

The loading progress bar percentage corresponds to specific loading stages. The earliest stages (0-20 percent) handle file discovery and level .asset parsing. The middle stages (20-60 percent) handle asset bundle loading, GUID resolution, and prefab instantiation. The later stages (60-90 percent) handle spawn table resolution, navmesh initialization, and network replication setup. The exact percentage at which the loading stalls or fails is the primary diagnostic signal for the failure class.

What is the most common loading failure cause across the cohort?

The most common loading failure cause across the 57 Studios™ cohort is a spawn table entry that references an item ID from a Workshop dependency that is not loaded. The map's own assets load correctly. The terrain and objects render. But one zombie spawn table entry references a zombie type that exists only in a mod that the tester has not subscribed to. The loading screen stalls at approximately 65 percent. The log shows Failed to find item or Missing spawn table entry. The fix is either to subscribe to the dependency or to remove the reference from the spawn table.

How do I check if a specific asset GUID exists in my bundle?

Open the bundle with a bundle inspection tool (AssetStudio or UnityBundleExplorer). Search the asset list for the GUID. If the GUID is not present, the asset was not included in the bundle build. Rebuild the bundle with the asset assigned to the correct bundle in Unity Editor.

Why does -ValidateAssets report errors for assets that look correct in the editor?

The editor does not apply the same validation checks. An asset that appears correct in the editor viewport may have a missing mesh reference, an unreadable navmesh, or a non-power-of-two texture. The validation checks that -ValidateAssets applies are deep inspections that the editor viewport does not perform. Every validation error reported by -ValidateAssets is a real issue that will affect the game client's loading behavior.

Can a loading failure be caused by a corrupted Workshop cache?

Yes. The Workshop cache at %PROGRAMFILES(X86)%\Steam\steamapps\workshop\content\304930\ stores downloaded mod files. A corrupted cache file can cause loading failures that appear to be asset bundle issues. Clearing the cache for the affected Workshop item and re-downloading resolves cache-corruption loading failures. The cohort recommendation is to clear the Workshop cache before beginning any diagnostic procedure for a map that is loaded from the Workshop rather than from a local folder.

How do I fix a GUID conflict between two asset bundles?

Identify both assets that share the conflicting GUID from the log entry. Open the map's Unity project. Locate both assets. Regenerate the GUID for one asset by deleting its Unity resource file and re-importing the asset into the project. Rebuild the bundle. The cohort recommendation is to regenerate the GUID for the asset that has fewer references, because the re-import process may also update the references.

What does it mean when the loading bar stalls at exactly the same percentage every time?

A stall at the exact same percentage across repeated loading attempts indicates a deterministic failure: the engine encounters the same missing asset, corrupt bundle entry, or GUID conflict at the same loading stage every time. A stall at a different percentage each time indicates a race condition or a memory issue. Deterministic stalls are traceable through the log file. Non-deterministic stalls are more difficult to diagnose and may require hardware profiling.

Can I use -ValidateAssets on a dedicated server?

-ValidateAssets is a client-side flag. It runs when the game client loads a map. The dedicated server does not run -ValidateAssets automatically. To validate assets on a dedicated server, load the map through the game client once with the -ValidateAssets flag, fix all reported errors, then copy the corrected map to the server.

Why does my map load correctly on the first attempt but fail on subsequent attempts?

This pattern typically indicates a Workshop cache issue. The first load succeeds because the map is loaded from a local folder. Subsequent loads attempt to load from the Workshop cache, which may contain a stale version of the map or a corrupted cache entry. Clear the Workshop cache for the map and re-subscribe, or load the map from the local Maps/ folder instead of through the Workshop subscription.

Best practices

• Run -ValidateAssets on every major build before the map is tested by anyone other than the author.
• Maintain a test checklist that includes loading the map through the game client (not the editor) after every significant change.
• Keep a log of every loading failure and its resolution, including the log message signature that identified the failure.
• Test the map on both the game client and a dedicated server before considering the loading pipeline validated.
• Load the map from the Workshop (not from the local Maps/ folder) before publishing to confirm the Workshop distribution path works.
• Use a separate Steam account for testing to isolate the subscriber experience from the authoring experience.
• Document all Workshop dependencies in the map description so that testers and server operators know which mods to install.
• Clear the Workshop cache before each major test cycle to eliminate cache corruption as a variable.
• Keep a backup of the previous working bundle build so that a failed rebuild can be rolled back without delaying the test cycle.
• When diagnosing a loading failure for a tester, ask for the exact loading percentage at which the failure occurred and a copy of Client.log.

Advanced considerations

Loading failures on lower-end hardware

A map that loads successfully on the author's development machine may fail on a lower-end machine with less RAM, a slower hard drive, or an integrated GPU. The most common lower-end loading failures are: out-of-memory errors during bundle decompression (maps with large custom texture atlases), GPU timeouts during shader compilation (maps with custom shaders that the GPU cannot compile within the timeout window), and disk I/O timeouts during level data streaming (maps with large terrain data on a mechanical hard drive).

The cohort recommendation is to test the map on at least one machine that is below the author's development specification before publishing. If a lower-end machine fails to load the map, the most effective fixes are: reduce the texture atlas resolution, remove custom shaders in favor of vanilla Unturned™ shaders, and reduce the terrain heightmap resolution.

Loading failures during Workshop distribution

A map that loads correctly from the local Maps/ folder may fail when loaded through the Workshop distribution path. The Workshop download process can produce incomplete downloads (network interruption during a large map download), corrupted bundle files (Steam's file verification fails but the cache is not cleared), or version mismatch (the Workshop entry points to an older version while the local folder has the updated version).

The cohort recommendation is to simulate the Workshop distribution path by clearing the local copy, subscribing to the map through the Workshop, and loading it through the game client before announcing the map as publicly available. This test catches Workshop-specific loading failures that the local-loading test does not.

Loading failures from Workshop dependency version drift

When a map depends on other Workshop items, those items may receive updates that change their asset GUIDs, remove referenced assets, or restructure their bundle organization. A map that loaded correctly six months ago may fail to load today because a dependency updated and the map's references to the dependency's assets are now broken.

The cohort recommendation is to pin Workshop dependency versions where possible and to re-test the map after every dependency update. If a dependency update breaks the map, the resolution is either to update the map's references to match the new dependency version or to remove the dependency and replace the affected assets with locally-authored equivalents.

Appendix A: Quick-reference diagnostic card

The following card condenses the diagnostic workflow into a single reference block. Print or bookmark this card for use during loading failure diagnosis.

MAP LOADING FAILURE DIAGNOSTIC CARD
====================================

1. Capture Client.log after failure.
2. Search log for: Error, Failed, Missing, Conflict, GUID, not found.
3. Note exact loading percentage of failure.
4. Map percentage to failure class:
   0-20%  : Level .asset or folder structure
   20-50% : Asset bundle loading or GUID resolution
   50-70% : Spawn table entry resolution
   70-90% : Navmesh or network replication init
   90-100%: Lighting or post-processing init

5. Apply class-specific fix.
6. Re-test. If still failing, check for cascade patterns.
7. Run -ValidateAssets after successful load.

Appendix B: Client.log keyword search reference

The following keywords are the most diagnostically valuable patterns to search for in Client.log when diagnosing a loading failure. Each keyword is listed with the failure class it indicates and the recommended follow-up action.

Keyword	Failure class	Follow-up action
Failed to load level bundle	Level .asset bundle reference	Verify the Bundle field in the level .asset
Could not find bundle	Missing bundle file	Confirm the bundle file exists at the expected path
Missing asset	Prefab or asset reference	Identify the missing asset path and re-add it to the bundle
Failed to resolve GUID	GUID resolution failure	Check for GUID collisions or missing bundle
GUID conflict	Duplicate GUID across two assets	Regenerate one of the conflicting GUIDs
NullReferenceException	Broken component or null reference	Locate the component in the editor and fix the null reference
Failed to find item	Spawn table references invalid item ID	Remove or correct the invalid spawn table entry
Bundle not found	Bundle file path mismatch	Confirm the bundle file is in the correct Bundles/ directory
Texture not found in bundle	Texture excluded from bundle build	Rebuild the bundle with the texture included
Missing zombie asset	Zombie spawn table entry invalid	Correct the zombie spawn table entry
Water reflection count exceeded	Multiple water reflections enabled	Disable planar reflections on all but one water volume
Navmesh bake incomplete	Navmesh does not cover playable area	Re-bake the navmesh with corrected agent settings
Parsing error in	.dat file malformed	Open the reported .dat file and fix the syntax error

Appendix C: Bundle integrity checklist

Before publishing a map, verify each item on this checklist to confirm bundle integrity.

• Bundle file(s) exist in the Bundles/ directory at the expected relative paths
• Each bundle file is larger than 1 KB (zero-byte bundles indicate failed builds)
• Each bundle file starts with the UnityFS magic number (verified with a hex editor)
• The master bundle name in the level .asset Bundle field matches the actual bundle file name exactly
• All prefabs in the Unity project are assigned to a bundle in the Asset Bundle panel
• All textures referenced by materials in the bundle are also assigned to a bundle
• The bundle was rebuilt after the most recent prefab or texture change
• Workshop dependency bundles are loaded in the correct order (dependencies before dependents)

Appendix D: Worked example resolving a cascade loading failure

The worked example below traces a real loading failure through the diagnostic workflow. The map in this example is a fictional medium-sized survival map called "Timber Valley."

Initial symptom

The author reports that Timber Valley loads to approximately 53 percent on the loading bar and then stalls indefinitely. The spinner continues to animate but the progress bar does not advance. The map does not crash; it remains on the loading screen until the player closes the game.

Step 1: Capture the failure evidence

The author opens Client.log and searches for error keywords. The log contains the following entries in sequence:

[17:32:01] Loading level: Timber Valley
[17:32:05] Loading bundle: TimberValley_MasterBundle
[17:32:08] Asset: Failed to resolve GUID: a1b2c3d4e5f6a7b8c9d0e1f2
[17:32:08] Asset: Missing asset: a1b2c3d4e5f6a7b8c9d0e1f2
[17:32:09] Spawn: Failed to find item: 45201
[17:32:09] Spawn: Failed to find item: 45202
[17:32:09] Spawn: Failed to spawn zombie: TimberValley_Zombie_Civilian
[17:32:10] Loading progress stalled at 53%

Step 2: Map to failure class

The stall at 53 percent (the 50-70 percent range) and the spawn-related error messages indicate a spawn table entry resolution failure. The GUID resolution failure and the missing asset error at the same stage indicate that the spawn tables reference assets that are not loaded.

Step 3: Class-specific diagnosis

The log shows three error categories: a GUID resolution failure, a missing asset, and two spawn table failures. The GUID resolution failure is the earliest error in the sequence. The spawn table failures are cascade errors from the missing asset. The author opens the missing asset's GUID in the Unity Editor and discovers that the asset is a custom zombie model that was removed from the master bundle during a previous cleanup pass but was not removed from the zombie spawn table.

Step 4: Repair

The author adds the zombie model back to the master bundle in Unity Editor. The author also reviews the zombie spawn table to confirm that the removed asset is the only missing entry. Both the model and the spawn table reference are restored. The bundle is rebuilt and the map is re-exported.

Step 5: Re-validate

The author re-runs -ValidateAssets. The validation passes with zero errors. The map loads through the game client 100 percent and the player can see zombies in the Timber Valley civilian area. The cascade failure is resolved.

Appendix E: Client.log versus Server.log comparison

Understanding the differences between the client log and the server log is essential for diagnosing loading failures that occur in one environment but not the other.

Aspect	Client.log	Server_[ID].log
File location	%LOCALAPPDATA%\Unturned\Logs\Client.log	U3DS/Servers/<ServerID>/Server_<ID>.log
Created by	The game client when it launches	The dedicated server process
Error detail level	Full asset validation detail including texture and mesh diagnostics	Reduced detail; focuses on loading errors and runtime errors
GUID conflict reporting	Reports all conflicts	Reports only conflicts that affect loaded assets
Spawn table errors	Reports missing entries during level load	Reports missing entries during level load and also during runtime spawn attempts
Network errors	Limited (only affects the local player's perspective)	Full network replication error reporting
Save data errors	Not applicable (client does not write server save data)	Reports save data read/write errors
Workshop download errors	Reports download issues for the subscribing client	Reports download issues for server Workshop items
Command errors	Reports errors from the client console	Reports errors from Commands.dat parsing

The cohort recommendation is to check both log files when a loading failure occurs on the dedicated server but not on the client, or vice versa. The error that appears in only one log file is the one that is specific to that environment.

Appendix F: Loading failure triage priority

When a map fails to load and the server or client operator needs to restore service quickly, the following triage priority list identifies the most common and most easily resolved failure causes first.

Priority	Check	Time to verify	Resolution time
1	Is the map folder in the correct Maps/ directory?	10 seconds	10 seconds
2	Does the Map command in Commands.dat match the folder name exactly (including case)?	10 seconds	10 seconds
3	Are all Workshop dependencies installed and listed in the correct order in WorkshopDownloadConfig.json?	30 seconds	30 seconds to add missing entries
4	Is the Workshop cache clear? Corruption is a common cause of bundle loading failures.	30 seconds to locate the cache folder	30 seconds to clear
5	Does the level .asset Bundle field match the master bundle name?	15 seconds to open the file	15 seconds to correct
6	Does -ValidateAssets produce zero errors?	2-5 minutes to run	Variable per error

The cohort recommendation is to run through priorities 1 through 5 before opening the Unity Editor for bundle inspection. Most loading failures on servers are resolved at priorities 3 or 4 (missing dependencies or cache corruption), which do not require any map modification.

Appendix G: Asset bundle integrity testing procedure

The following procedure tests whether an asset bundle file is intact and loadable without loading the full map. This is useful when a loading failure is suspected to be caused by a corrupt bundle but the author wants to confirm before rebuilding.

1. Locate the suspected bundle file in the Bundles/ directory.
2. Check the file size. A bundle that is smaller than 1 KB is almost certainly corrupt or empty. A healthy bundle for a map with custom assets is typically 1 MB to 200 MB depending on the number and size of the assets.
3. Open the bundle file in a hex editor. The first four bytes must be UnityFS (hex: 55 6E 69 74 79 46 53). Any other header indicates the file is not a valid Unity asset bundle.
4. If the header is valid, attempt to load the bundle on a test client by placing it in the Bundles/ directory of a map that already loads correctly. If the test map loads without errors, the bundle is intact.
5. If the header is invalid or the bundle fails to load on a test map, re-export the bundle from Unity Editor with the correct build settings.

Cross-references

• Workshop Upload Process - the next article in the tutorial pipeline, covering how to upload a validated map to the Steam Workshop.
• Dedicated Server Testing and Validation - the previous article in the tutorial pipeline, covering the server-side testing procedure that catches loading failures before the map is published.
• Steam Workshop Submission - the Workshop publishing workflow that receives the validated map from this article.
• Setting Up an Unturned Server - the server setup procedure for dedicated server testing.
• Workshop Content on Dedicated Servers - how the dedicated server loads Workshop content, including the dependency order that affects map loading.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Full loading failure diagnostic reference with symptom-cause-fix table, ValidateAssets interpretation, GUID collision resolution, and missing asset diagnosis.