Mod Not Loading

A modder finishes a build, copies the output into the Unturned™ mods directory or publishes to the Steam Workshop, launches the game, and watches the mod fail to load. The mod's items do not appear in the editor's item list. The console logs no errors, or the console logs a vague "could not load asset" without a stack trace. The Workshop entry shows as subscribed but does not appear in-game. Every one of these symptoms means the same thing from the modder's perspective: the mod is not loading.

Mod-load failures are the single highest-volume troubleshooting category in the 57 Studios cohort survey. Unlike compile errors, which produce explicit error codes in the Unity Console, mod-load failures often produce no visible error at all. The mod is simply absent. Diagnosing the failure requires methodically eliminating possible causes, beginning with the most likely.

This article documents fifteen distinct causes of an Unturned mod that does not load, identifies the symptom that points at each cause, and provides a resolution. The diagnostic flow at the start of the article walks the modder through the elimination sequence. The cause-by-cause section that follows provides per-cause detail. The appendices document the file formats and log signatures that surface most often during diagnosis.

Prerequisites

• The mod has compiled successfully. If it has not, return to Unity Compiler Errors first.
• The master bundle has built successfully. If it has not, return to Master Bundle Export.
• Unturned installed and launchable.
• File Explorer access to the Unturned installation folder and the mod's output folder.
• Notepad++ or another text editor installed for reading game logs and .dat files.
• A backup of the mod's source folder before making changes.

What you'll learn

• The fifteen distinct causes of an Unturned mod that does not load.
• How to read the Unturned game log to identify which cause applies.
• How to verify the master bundle's build target.
• How to confirm a GUID is unique across loaded mods.
• How to check that English.dat is present and correctly formatted.
• How to inspect the meta.dat file for malformed entries.
• How to resolve Workshop sync issues that prevent download completion.
• How to identify antivirus interference with the mod's files.
• How to detect Unity-version mismatches between the bundle and the game.
• How to distinguish server-side mods from client-side mods and load each correctly.
• How to identify RocketMod and OpenMod plugin conflicts.
• How to verify file permissions and encoding on the mod's .dat files.

Background: how Unturned loads a mod

The Unturned game loads mods during startup. The load sequence is:

1. The game enumerates mod folders under the configured mods directories (Steam Workshop content folder, Bundles/Sources/ under the install, and any configured server mod directory).
2. For each folder, the game reads the meta.dat file (if present) to identify the mod.
3. The game reads every .dat file in the folder tree. Each .dat file defines a single asset (an item, vehicle, animal, weather pattern, or similar).
4. For each .dat file, the game validates the asset's GUID, ID, and required fields.
5. For each asset, the game loads the referenced bundle file and resolves the prefab references.
6. For each asset, the game reads the corresponding English.dat (or other language file) to load display strings.
7. The asset is registered in the game's internal asset database under its GUID and ID.

A failure at any step skips the affected asset but does not necessarily stop the game from loading other assets. This is why a mod can partially load: some items appear in-game while others do not. The diagnostic approach in this article is to identify which step is failing for the affected assets.

Where to find the game log

The Unturned game log is the most important diagnostic file for any mod-load failure. The log records every asset the game attempted to load and the result of each attempt.

On Windows the log is at:

%LOCALAPPDATA%Low\Smartly Dressed Games\Unturned\Player.log

The path includes %LOCALAPPDATA%Low rather than %LOCALAPPDATA%; the Low suffix is a Windows convention for low-integrity application data. The path can be pasted directly into the File Explorer address bar.

Open the log in Notepad++ and scroll to the end. The last 200 lines describe the most recent game session, including the mod-load sequence. Search the file (Ctrl+F) for the mod's folder name to jump to the relevant section.

Did you know?

The Unturned game log is overwritten on every launch. To preserve a log from a failed launch, copy the file to a backup location before launching the game again. The cohort recommendation is to keep a troubleshooting-logs/ folder alongside the mod's source repository for archived logs.

The fifteen causes

The table below summarises the fifteen causes documented in this article. Each row links the symptom the modder will observe to the cause and the resolution method. The table is the cohort's first-pass triage chart.

Cause	Typical symptom	Resolution
1. Wrong target platform for bundle	"Bundle is not compatible with this platform" in log	Method 1
2. Missing English.dat for an item	Item appears with raw ID as its name	Method 2
3. Duplicate GUID with another loaded mod	"Duplicate GUID" warning in log	Method 3
4. Reserved ID range collision	Item replaced by or replaces a vanilla item	Method 4
5. meta.dat malformed or missing	Entire mod folder is silently skipped	Method 5
6. Wrong encoding on .dat file	".dat parse error" or item silently absent	Method 6
7. Bundle compiled with wrong Unity version	"Could not load bundle" in log	Method 7
8. Mod folder not under expected directory	Mod is not enumerated at all	Method 8
9. Server-side mod loaded client-side without bundle download	Joining client cannot see modded items	Method 9
10. Mod file permissions blocked by antivirus	Mod files present but unreadable	Method 10
11. Steam Workshop did not finish downloading	Workshop entry subscribed but missing files	Method 11
12. Conflicting RocketMod/OpenMod plugin	Mod is overridden by plugin	Method 12
13. Mod expects assets renamed mid-update	Specific assets missing while others load	Method 13
14. Bundle file missing from the mod folder	"Failed to find bundle" in log	Method 14
15. Path length exceeds Windows limit	Some files unreadable, intermittent	Method 15

Diagnostic flow

The flowchart below walks the modder through the elimination sequence. Begin at the top and follow each branch until a cause is identified.

Cause and remedy reference

Cause 1: Wrong target platform for bundle

Symptom: Game log shows "Bundle is not compatible with this platform" or "AssetBundle was not built for this platform" near the entry for the mod's bundle file. The mod folder is enumerated but the bundle fails to load. Items defined by the mod do not appear in-game.

Root cause: The master bundle was built with a target platform that does not match the running game's platform. Unturned runs on Windows64 by default; a bundle built for StandaloneOSX, StandaloneLinux64, or any non-Windows target is rejected by the Windows64 game.

Why it happens: The bundle build target is set in Unity's Build Settings dialog and persists per-project. A modder who previously built for a different platform (or who copied a project from a Mac modder) may have the wrong target set.

Fix:

1. Open the Unity project.
2. Navigate to File → Build Settings.
3. Confirm the Platform list shows "PC, Mac & Linux Standalone" as the active platform.
4. In the Target Platform dropdown on the right, select "Windows."
5. In the Architecture dropdown, select "x86_64."
6. Click "Switch Platform" if it is not greyed out.
7. Rebuild the master bundle. See Master Bundle Export for the full bundle build workflow.
8. Copy the new bundle into the mod's output folder, replacing the old bundle.
9. Restart Unturned and verify the mod loads.

Prevention: Confirm the build target is set to Windows x86_64 before every bundle build. The cohort recommendation is to add a check to any build script: read the project's EditorBuildSettings.asset and refuse to build if the target is not Windows64.

Cause 2: Missing English.dat for an item

Symptom: The item loads in-game but its name appears as the raw numeric ID (e.g., "1234" instead of "Steel Sword"). The description is empty. The /giveitem 1234 command works but autocomplete cannot find the item by name.

Root cause: Unturned reads display strings from a language file (typically English.dat) located in the same folder as the item's .dat file. If the language file is missing, the item loads but with no display strings, falling back to the raw ID.

Why it happens: The modder created the item's .dat file but did not create the matching English.dat. Alternatively, the English.dat was renamed, deleted, or placed in the wrong folder.

Fix:

1. Locate the item's folder under the mod's Bundles directory.
2. Confirm the folder contains both <ItemName>.dat and English.dat.
3. If English.dat is missing, create it. The minimum content is:

   Name <Display Name>
   Description <Description text>

4. Save the file with ANSI encoding (not UTF-8). See Method 6 for encoding details.
5. Restart Unturned and verify the item displays its name correctly.

Prevention: The cohort recommendation is to generate English.dat programmatically from the same source data that generates the item's .dat file. The 57 Studios cohort uses a Python script that reads a CSV of item definitions and emits both files. The script reduces the rate of missing-language-file failures to zero across the cohort.

Pro tip

Unturned supports multiple language files in the same folder. A modder shipping in multiple languages places English.dat, Spanish.dat, French.dat, etc., side by side. The game selects the language file that matches the player's language setting. Modders shipping a single language can ship only English.dat; the game falls back to English when the player's selected language has no matching file.

Cause 3: Duplicate GUID with another loaded mod

Symptom: Game log shows "Duplicate GUID <guid> between mod A and mod B. Loading first; skipping subsequent." The mod's items either do not appear or replace another mod's items unexpectedly.

Root cause: Two .dat files (in the same mod or in different loaded mods) declare the same GUID. The game loads the first and skips the rest. Which one wins depends on load order, which is not deterministic.

Why it happens: The modder copied an existing item as a template and forgot to regenerate the GUID. Or two unrelated mods coincidentally chose the same GUID.

Fix:

1. Read the game log to identify the duplicate GUID and both mods involved.
2. If the duplicate is between two assets in the same mod, the modder can fix it directly: open one of the .dat files in Notepad++, replace the GUID line with a freshly generated GUID, and save.
3. If the duplicate is between this mod and another mod, the modder can either change this mod's GUID or coordinate with the other mod's author. The cohort recommendation is to change this mod's GUID; the other mod's GUID may already be referenced by saves, servers, or downstream mods.
4. Generate a new GUID. On Windows in PowerShell: [guid]::NewGuid().ToString(). Use the result as the new GUID line.
5. Restart Unturned and verify the conflict is resolved.

Prevention: The cohort recommendation is to maintain a project-internal GUID registry that lists every GUID the mod has assigned. The registry can be a single text file in the project root. Generating new GUIDs and writing them to the registry before adding them to any .dat file prevents within-project duplicates entirely. Cross-mod duplicates can be detected by searching the registry for any GUID listed in publicly published mods.

See GUID Conflicts Between Mods for a deeper treatment of the cross-mod case.

Cause 4: Reserved ID range collision

Symptom: The item's numeric ID is in the vanilla Unturned reserved range (0-2000). Either the item replaces a vanilla item (incorrectly), or the game uses the vanilla item and ignores the modder's definition.

Root cause: Smartly Dressed Games reserves the ID range 0-2000 for vanilla Unturned content. Mod IDs that fall in that range collide with vanilla IDs and produce undefined behaviour at load time.

Why it happens: The modder did not know about the reserved range, or copied an ID from a tutorial that used reserved-range IDs as examples.

Fix:

1. Open the item's .dat file in Notepad++.
2. Locate the ID line.
3. Change the ID to a number above 2000. The cohort-recommended range for new mods is 50000+ to avoid collision with both vanilla and other major modders.
4. Update any references to the item's ID in other .dat files in the same mod.
5. Update any English.dat references if applicable.
6. Restart Unturned and verify the item loads correctly.

Prevention: The cohort recommendation is to reserve an ID range for each mod project at the start of development. The cohort maintains a public ID registry that lets modders claim ranges to avoid cross-mod collisions. See Project Folder Structure and GUIDs for the cohort's ID-allocation guidance.

Cause 5: meta.dat malformed or missing

Symptom: The entire mod folder is silently skipped. The game log does not mention the mod at all. The mod folder is present in the correct location.

Root cause: Unturned reads each mod folder's meta.dat to identify the mod. If meta.dat is missing or malformed, the game cannot identify the mod and skips the folder.

Why it happens: The modder packaged the mod for distribution without including meta.dat. Or the modder edited meta.dat and introduced a syntax error.

Fix:

1. Open the mod folder in File Explorer.
2. Confirm meta.dat exists in the folder root.
3. If meta.dat is missing, restore it from backup or generate a new one. A minimal meta.dat:

   ID 12345
   Type Workshop
   Required_Search_Filter false

4. If meta.dat is present, open it in Notepad++ and confirm the syntax matches the example above.
5. Save the file with ANSI encoding (see Method 6).
6. Restart Unturned and verify the mod is now enumerated.

Prevention: The cohort recommendation is to template the meta.dat and copy it into every new mod folder at project creation. Maintain a single canonical meta.dat template in the project root.

Cause 6: Wrong encoding on .dat file

Symptom: Game log shows ".dat parse error" or the item silently does not load. The modder has confirmed the file is present and the syntax appears correct in the editor.

Root cause: Unturned reads .dat files as ANSI text. A file saved with UTF-8 BOM (byte-order-mark) prefix is misread because the BOM bytes appear as garbage at the start of the file. The parser fails on the first line.

Why it happens: Notepad and some other editors save with UTF-8 BOM by default. The modder did not change the encoding setting.

Fix:

1. Open the affected .dat file in Notepad++.
2. Look at the bottom-right corner of the Notepad++ window. The current encoding is displayed there.
3. If the encoding shows "UTF-8-BOM," click Encoding → Convert to ANSI in the menu bar.
4. Save the file.
5. Restart Unturned and verify the file is now read correctly.

Prevention: See How to Save a .dat File with Correct Encoding for the complete encoding guidance. The cohort recommendation is to configure Notepad++ to default to ANSI encoding for new files in the modding project folder.

Common mistake

Saving meta.dat with UTF-8 BOM. The BOM bytes appear as garbage at the start of the file. The parser fails on the first line. The game silently skips the mod. The fix is the same as for any other .dat file: convert the encoding to ANSI in Notepad++.

Cause 7: Bundle compiled with wrong Unity version

Symptom: Game log shows "Could not load bundle" or "AssetBundle version mismatch." The bundle file is present in the correct location and has the correct target platform.

Root cause: Unity asset bundles are tied to the Unity editor version that built them. Unturned ships with a specific Unity version baked in; bundles built with a different Unity version are not guaranteed to load. The current Unturned release expects bundles built with the Unity version listed in the Smartly Dressed Games Modding Documentation.

Why it happens: The modder built the bundle with a newer (or older) Unity version than Unturned expects. The Unity Hub auto-update may have moved the modder to a newer version unintentionally.

Fix:

1. Open the Unity project.
2. Locate ProjectSettings/ProjectVersion.txt in the project folder. Open it in Notepad++.
3. Compare the recorded version with the version Smartly Dressed Games has published as the current required version.
4. If the versions differ, install the correct Unity version via Unity Hub. See How to Install Unity Editor.
5. Open the project with the correct Unity version.
6. Rebuild the master bundle.
7. Copy the new bundle into the mod's output folder.
8. Restart Unturned and verify the bundle loads.

Prevention: Pin the required Unity editor version in Unity Hub so it cannot be accidentally uninstalled. Confirm the project's ProjectVersion.txt matches the Unturned requirement before every bundle build.

Cause 8: Mod folder not under expected directory

Symptom: The mod is not enumerated at all. The game log does not mention the mod. The mod folder is present somewhere on disk.

Root cause: Unturned enumerates mods from specific directories. A mod folder placed in any other location is not enumerated.

The expected directories:

Directory	Used for
Steam Workshop content folder (steamapps/workshop/content/304930/)	Workshop-subscribed mods
<Unturned install>/Bundles/Sources/	Local mods loaded as bundle sources
<server install>/Servers/<instance>/Workshop/Content/	Server-side workshop content
<server install>/Bundles/	Server-side local bundles

Why it happens: The modder copied the mod into a folder like Documents, Downloads, or the desktop. Or the modder placed it under the Unturned install but in a sibling folder that is not enumerated.

Fix:

1. Identify the appropriate target directory from the table above. For local testing on the client, <Unturned install>/Bundles/Sources/<ModName>/ is the cohort-recommended location.
2. Move the entire mod folder (the folder containing meta.dat) into the target directory.
3. Restart Unturned and verify the mod is now enumerated.

Prevention: The cohort recommendation is to use a symbolic link from the mod's build output folder to the Unturned Bundles/Sources/ directory. The symlink lets the modder rebuild the bundle without copying files; the next game launch always sees the latest bundle. On Windows: mklink /D "C:\Program Files (x86)\Steam\steamapps\common\Unturned\Bundles\Sources\MyMod" "C:\Project Folder\MyMod\BuildOutput".

Cause 9: Server-side mod loaded client-side without bundle download

Symptom: A player joins a modded server but cannot see the modded items. The server shows the items in the inventory; the client shows them as missing or generic placeholders.

Root cause: Unturned distinguishes server-side mods (gameplay logic) from content mods (items, vehicles, models). Server-side mods do not require client-side download because they do not contain client-visible content. Content mods require client-side download because the client needs the bundles to render the items.

Why it happens: The server admin enabled a content mod on the server without configuring the Workshop download mechanism, or the client did not subscribe to the Workshop entry.

Fix:

1. Confirm the mod is a content mod (defines items, vehicles, or other client-visible content) rather than a server-side gameplay mod.
2. On the server, confirm the mod is listed in the server's Workshop content. The server's WorkshopDownloadConfig.json should include the mod's Workshop ID.
3. On the client, subscribe to the mod's Workshop page in Steam.
4. Restart Unturned on the client to trigger the Workshop download.
5. Verify the client now sees the modded items when joining the server.

Prevention: The cohort recommendation for content-mod authors is to publish to the Steam Workshop and instruct server admins to add the Workshop ID to their server's WorkshopDownloadConfig.json. Clients connecting to the server will then auto-download the mod via Steam's Workshop sync.

Cause 10: Mod file permissions blocked by antivirus

Symptom: The mod folder is present in the correct location. The files appear to be there. The game log shows "Access denied" or "Could not open file" for the mod's files.

Root cause: Antivirus tools occasionally quarantine or block access to files they consider suspicious. Asset bundles and .dat files with binary content may trip heuristic detection.

Why it happens: The antivirus has heuristics that flag the file as suspicious. The mod is unsigned, which raises the heuristic confidence.

Fix:

1. Open the antivirus dashboard.
2. Check the quarantine list for any file from the mod's folder.
3. If quarantined files are present, restore them and add the mod's folder to the antivirus exclusion list.
4. If no files are quarantined, add the mod folder and the Unturned installation folder to the antivirus exclusion list pre-emptively.
5. Restart Unturned and verify the mod loads.

Prevention: Configure antivirus exclusions for the Unturned installation folder, the Steam Workshop content folder, and the modder's project folder during initial machine setup. The exclusions prevent both this failure mode and the related Unity import failures documented in Unity Won't Open My Project.

Cause 11: Steam Workshop did not finish downloading

Symptom: The mod's Workshop entry shows as subscribed in Steam. The mod's files are partially present or absent in the Workshop content folder. The mod does not load.

Root cause: Steam Workshop downloads can fail or be interrupted. Steam may report the subscription as successful while the download is still in progress, or the download may have failed silently.

Why it happens: Network interruption during the download. Steam was busy with other downloads. The download was blocked by a Steam server-side issue.

Fix:

1. Open Steam.
2. Navigate to Library → Downloads.
3. Confirm no Workshop downloads are in progress or queued.
4. If downloads are queued, allow them to complete.
5. If downloads have failed, force a re-validation of the Workshop content by running:

   steam://validate/304930

   in a browser address bar or as a Run dialog command. The URL triggers Steam's Workshop validation for the Unturned app (ID 304930).
6. Wait for validation to complete.
7. Launch Unturned and verify the mod is now present.

Prevention: The cohort recommendation is to confirm Workshop downloads have completed before launching Unturned after subscribing to a new mod. The Downloads tab in Steam shows pending and failed downloads.

Cause 12: Conflicting RocketMod/OpenMod plugin

Symptom: The mod is enumerated and loaded by Unturned, but its functionality is overridden in-game. Items appear but commands like /giveitem use a different definition than the one the modder authored.

Root cause: RocketMod and OpenMod are server-side plugin frameworks that can register their own item handlers, command handlers, and event subscribers. A plugin that registers a handler for an item the modder also defines can override the mod's behaviour at runtime.

Why it happens: The server admin installed a plugin that overrides the modder's content. Or the modder's mod targets a feature that a popular plugin also targets, and the plugin's registration wins by load order.

Fix:

1. On the server, navigate to the plugins directory (Servers/<instance>/Rocket/Plugins/ for RocketMod, Servers/<instance>/OpenMod/ for OpenMod).
2. List the installed plugins.
3. Identify any plugin whose functionality overlaps with the mod's intended behaviour.
4. Disable the overlapping plugin by moving its .dll out of the plugins folder.
5. Restart the server and verify the mod's behaviour now appears as expected.
6. If the plugin must remain installed, coordinate with the plugin author or modify the plugin's configuration to exclude the modder's items.

Prevention: The cohort recommendation for content-mod authors is to publish a list of known incompatible plugins in the mod's Workshop page description. The cohort recommendation for server admins is to maintain an inventory of installed plugins and to test new plugin installations against the existing mod set before deploying to production.

Cause 13: Mod expects assets renamed mid-update

Symptom: Specific assets in the mod are missing while others load correctly. The game log shows "Asset not found" for the missing assets.

Root cause: The modder renamed an asset in the Unity project (a prefab, texture, or material) but the bundle still references the old name. Unity's asset reference system uses GUIDs internally, but bundle references can drift if assets are moved between folders or recreated.

Why it happens: The modder reorganised the project's Assets folder and Unity could not auto-update every reference. Or the modder recreated an asset by deleting and re-importing it, which assigned a new GUID.

Fix:

1. Open the Unity project.
2. Navigate to the asset that fails to load.
3. Confirm the asset's GUID matches what the bundle expects. The bundle's expected GUID can be inspected in the bundle inspector tool, or read from the .meta file Unity generates alongside the asset.
4. If the GUID has drifted, re-link the references in the affected prefabs.
5. Rebuild the bundle.
6. Copy the new bundle into the mod's output folder.
7. Restart Unturned and verify the asset now loads.

Prevention: Avoid renaming or moving assets after they have been added to a bundle. If renames are unavoidable, run the Unity reference-updater (Edit → Refresh All) and rebuild the bundle immediately afterwards.

Cause 14: Bundle file missing from the mod folder

Symptom: Game log shows "Failed to find bundle <bundle path>." The mod folder is present and meta.dat is valid; the bundle file itself is missing or has the wrong name.

Root cause: The bundle file referenced by the mod's .dat files is not present at the expected path. The reference may be to an old bundle name, or the bundle file may not have been copied into the output folder.

Why it happens: The modder rebuilt the bundle with a different name and forgot to update the .dat file references. Or the build script copied the .dat files but not the bundle. Or the bundle was deleted accidentally.

Fix:

1. Read the game log to identify the bundle path the game is looking for.
2. Confirm the bundle file exists at that path. If not, copy the bundle into place.
3. If the bundle exists under a different name, either rename the bundle or update the .dat file references to match.
4. Restart Unturned and verify the bundle loads.

Prevention: Automate the bundle copy step. The cohort recommendation is to use a PowerShell script that copies the bundle from the Unity build output to the mod's output folder as part of the build. The script removes the manual step where the modder might forget the copy.

Cause 15: Path length exceeds Windows limit

Symptom: Some mod files are unreadable, intermittently. The mod partially loads. The failure is not reproducible at every launch.

Root cause: Windows imposes a 260-character path length limit by default. A deeply nested Unturned install or Workshop content folder can place mod files at paths that exceed the limit.

Why it happens: Steam's Workshop content folder is itself nested under the Steam install (steamapps/workshop/content/304930/<id>/). A mod with deeply nested asset folders inside its own structure can push individual files past 260 characters.

Fix:

1. Identify the longest file paths in the mod folder. On Windows in PowerShell:

   Get-ChildItem -Recurse "<mod folder>" | Sort-Object { $_.FullName.Length } -Descending | Select-Object -First 10 FullName, @{N='Length';E={$_.FullName.Length}}

2. If any file path exceeds 260 characters, restructure the mod's folder tree to reduce nesting depth.
3. Alternatively, enable Windows long-path support via the registry: set HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled to 1. Unturned and Unity both honour the setting.
4. Restart Unturned and verify the mod loads.

Prevention: Keep mod folder hierarchies shallow. The cohort recommendation is to use a maximum nesting depth of three folders inside the mod root (e.g., Items/Weapons/<ItemName>/).

Cause-by-symptom lookup

The table below sorts the fifteen causes by the symptom the modder is most likely to observe. The table is useful when the game log is unavailable or unreadable.

Symptom	Most likely causes
Mod folder not mentioned in log	5, 8, 10
"Bundle is not compatible" in log	1, 7
"Duplicate GUID" in log	3
"Failed to find bundle" in log	14
".dat parse error" in log	6
Item shows raw ID as name	2
Item replaces vanilla item	4
Workshop subscribed but no files	11
Mod loaded but behaviour wrong	12
Partial mod loading	13, 15
Client joins server, no modded items	9

Method comparison

Method	Time required	Risk level	Frequency in cohort survey
1. Fix bundle target platform	10-30 minutes	Low	Very high
2. Add English.dat	5 minutes	Low	High
3. Resolve GUID conflict	5-15 minutes	Medium	High
4. Move ID out of reserved range	5-15 minutes	Medium	Medium
5. Fix meta.dat	5 minutes	Low	Medium
6. Fix encoding	2 minutes	Low	Very high
7. Switch Unity version and rebuild	30 minutes to 2 hours	Low	Medium
8. Move mod to correct folder	2 minutes	Low	High
9. Configure server-side download	10-30 minutes	Medium	Medium
10. Add antivirus exclusion	5 minutes	Low	Low
11. Re-validate Steam Workshop	5-30 minutes	Low	High
12. Disable conflicting plugin	5-15 minutes	Medium	Medium
13. Re-link renamed assets	15-60 minutes	Medium	Medium
14. Restore missing bundle	5 minutes	Low	Medium
15. Shorten path or enable long paths	5-30 minutes	Medium	Low

Advanced considerations

Server-side vs client-side loading

Unturned distinguishes content that runs on the server from content that runs on the client. The two have different load paths and different failure modes.

Content type	Loaded by	Failure symptom
Item definition (.dat + bundle)	Both	Items missing in inventory
Vehicle definition	Both	Vehicles cannot be spawned
Server-only gameplay logic (RocketMod plugin DLL)	Server only	Behaviour missing on server
Map (Level/<MapName>/)	Both	Map missing from server browser
Animation override	Both	Animations fall back to defaults
Audio override	Both	Audio falls back to defaults

A modder publishing content for both single-player and multiplayer must verify the content loads on both sides. The cohort recommendation is to test on a local listen server (single-player + accept-multiplayer) before publishing.

Workshop ID vs internal mod ID

Two IDs are associated with every published mod:

• Steam Workshop ID: assigned by Steam when the mod is first published. Used in URLs and Workshop subscription.
• Internal mod ID (meta.dat ID field): assigned by the modder. Used by Unturned to identify the mod internally.

The two IDs are independent. A modder can have a Workshop ID of 2891754321 and an internal mod ID of 42. The Workshop ID is what other modders and server admins will reference; the internal mod ID is what Unturned uses for asset registration.

The cohort recommendation is to set the internal mod ID to a unique five-digit number per mod, documented in the mod's README.md. Steam handles the Workshop ID assignment automatically.

Bundle hash validation

Unturned validates that the bundle file's contents match the hash recorded in the bundle's manifest. A bundle that has been modified after the build (e.g., by an antivirus scrubber or a clumsy file edit) fails the hash check.

The fix for a hash check failure is to rebuild the bundle. There is no way to repair a corrupted bundle in place; the build pipeline is the only authority on bundle content.

Reading the Player.log effectively

The Unturned game log can be long (several thousand lines for a heavily modded game). The cohort-validated reading approach:

1. Open the log in Notepad++.
2. Press Ctrl+End to jump to the end of the file.
3. Read backwards from the end until the first "Loading complete" or similar marker. The lines after that marker describe runtime behaviour; the lines before describe the load sequence.
4. Search (Ctrl+F) for the mod's folder name. The first match is the load attempt; any subsequent matches are reload attempts or runtime references.
5. Read the 10-20 lines surrounding the match. The reason for the load failure is typically within that window.

Per-mod debug logging

The cohort recommendation for modders developing complex mods is to include a debug-log statement in any custom load code. The statement should write to the Unturned log via UnturnedLog.info(...) or the equivalent. Per-mod debug logging makes it possible to confirm the mod's code reached a specific point in the load sequence, which narrows the diagnosis when the load fails silently.

Did you know?

The cohort survey found that approximately 68 percent of mod-load failures resolve within 15 minutes when the modder reads the Player.log first. The remaining 32 percent take longer because the underlying cause is in a less obvious place (Workshop sync, antivirus, plugin conflict).

Frequently asked questions

My mod compiled successfully but doesn't appear in-game. What's the first thing to check?

Read the Unturned Player.log file. The log records every mod the game attempted to load. If the mod is mentioned, the log will indicate why the load failed (bundle target, GUID conflict, missing file, etc.). If the mod is not mentioned, the game did not enumerate it, which points to Cause 5 (meta.dat), Cause 8 (folder location), or Cause 10 (antivirus).

Why does my item show up with a number instead of its name?

Cause 2: English.dat is missing or in the wrong location. Unturned reads display strings from English.dat in the same folder as the item's .dat file. If the language file is absent, the item loads with the raw ID as its name. The fix is to create or restore English.dat with the Name and Description fields.

What does "Could not load AssetBundle" mean?

The bundle file was found but could not be loaded. The two most common causes are: the bundle was built for the wrong platform (Cause 1) or built with the wrong Unity version (Cause 7). Read the surrounding log lines to identify which.

How do I know if my GUID conflicts with another mod?

The Unturned game log writes a "Duplicate GUID" warning when it encounters a GUID it has already seen. The warning identifies both mods involved. If the log does not contain a duplicate warning, the GUID is unique among loaded mods. For pre-publication conflict checking, search the public 57 Studios cohort GUID registry. See GUID Conflicts Between Mods.

My Workshop mod is subscribed but the files aren't downloading. What's wrong?

Cause 11: the Workshop download has not completed. Open Steam → Library → Downloads to confirm. If no download is in progress and the files are absent, force a re-validation via steam://validate/304930. The validation triggers Steam to re-check Workshop content and re-download missing files. The full validation can take several minutes for a heavily modded Unturned installation.

Why does my mod work in single-player but not on the server?

Cause 9: the mod is content (items, vehicles) that requires both server and client to have the bundle. On the server, the Workshop ID must be in WorkshopDownloadConfig.json. On the client joining the server, Steam must have downloaded the mod via Workshop sync. The client and server bundle versions must also match.

What is the Player.log path on Windows?

%LOCALAPPDATA%Low\Smartly Dressed Games\Unturned\Player.log. Note the Low suffix on %LOCALAPPDATA% — this is the low-integrity application data path, not the standard one. The path can be pasted directly into the File Explorer address bar.

Why are my .dat files not being read correctly?

Cause 6: encoding. .dat files must be saved with ANSI encoding, not UTF-8 or UTF-8-BOM. Open the file in Notepad++ and check the encoding indicator at the bottom-right. If it shows anything other than ANSI, change it via Encoding → Convert to ANSI in the menu bar. See How to Save a .dat File with Correct Encoding for the full encoding guidance.

Can I have two mods with the same internal ID?

The internal mod ID in meta.dat is intended to be unique per mod. Two mods with the same ID may be silently merged by Unturned, with undefined results. The cohort recommendation is to assign each mod a unique five-digit ID and document it in the project's README.md.

My mod loads on my machine but not on my friend's machine. What's different?

The most common cause is that the friend's machine is missing the mod files entirely. Confirm the friend has subscribed to the Workshop entry and that Steam has downloaded it. The second most common cause is a Unity version mismatch: a bundle built on a beta Unity version may load on the build machine but not on a machine running a different Unity version (Cause 7). The third most common cause is antivirus on the friend's machine quarantining the mod files (Cause 10).

How do I generate a new GUID on Windows?

In PowerShell: [guid]::NewGuid().ToString(). The command emits a fresh GUID in the standard format. Copy the result into the .dat file's GUID line. The PowerShell GUID is cryptographically random and has effectively zero chance of collision with any other GUID in use.

Why does my mod load on the workshop content folder but not in Bundles/Sources?

The two folders have different conventions. Workshop content uses Steam's own folder layout, with the Workshop ID as the folder name. Bundles/Sources/ uses a free-form layout, with the modder choosing the folder name. The meta.dat requirements differ slightly: Workshop content requires the Type Workshop field, while Bundles/Sources/ content may use Type Sources or omit the field. Confirm the meta.dat matches the intended deployment.

How do I tell which Unity version my bundle was built with?

Open the bundle file in a hex editor. The first few bytes contain the Unity version string in plain text. Alternatively, open the project that built the bundle and read ProjectSettings/ProjectVersion.txt; the version recorded there is the version the bundle was built with.

Can I edit a .dat file in Notepad?

Notepad can read and edit .dat files. The cohort does not recommend Notepad because it defaults to UTF-8 with BOM on modern Windows, which causes Cause 6. Notepad++ is the cohort-recommended editor; it shows the encoding explicitly and lets the modder convert encoding if needed.

What does "Asset GUID mismatch" mean?

The bundle references an asset by GUID, but the asset is not present in the bundle under that GUID. This is Cause 13: assets renamed mid-update. The fix is to re-link the bundle's references and rebuild the bundle.

Can two mods reference the same bundle?

In principle yes, but the cohort does not recommend it. Each mod should have its own bundle, even if the bundle's contents overlap with another mod's. Shared bundles produce complex load-order dependencies and are difficult to debug.

Best practices

• Read the Player.log first, every time. The log is the single most informative diagnostic source.
• Confirm bundle target platform is Windows x86_64 before every build.
• Use ANSI encoding for every .dat file. Configure Notepad++ to default to ANSI for the modding project folder.
• Maintain a per-project GUID registry to prevent within-project duplicates.
• Allocate an ID range for each mod project; document the range in the project's README.
• Confirm Workshop downloads have completed before launching Unturned to test.
• Configure antivirus exclusions for the Unturned install folder, the Steam Workshop content folder, and the project folder.
• Use symbolic links from the build output to the Unturned Bundles/Sources/ directory to remove the manual copy step.
• Keep folder hierarchies shallow (maximum three levels of nesting).
• Test on a local listen server before publishing a content mod that targets multiplayer.
• Pin the Unity editor version in Unity Hub.

Cross-references

• Unity Compiler Errors — the previous article in the troubleshooting section, which addresses compile errors that prevent the mod from being built.
• Items Missing in Game — the next article, which addresses the narrower case of a loaded mod whose items do not appear.
• GUID Conflicts Between Mods — deeper treatment of the GUID-collision case.
• Master Bundle Export — the bundle-export workflow that produces the bundle the game tries to load.
• Project Folder Structure and GUIDs — the folder layout and GUID-allocation guidance.
• How to Save a .dat File with Correct Encoding — the encoding setup that prevents Cause 6.
• Installing Mods — the installation workflow from the player's perspective; understanding it helps modders diagnose the failure modes their users will encounter.
• Publishing — the publishing workflow that places the mod in the Workshop.
• Unity Asset Bundles Intro — Unity's official documentation on asset bundles.
• Smartly Dressed Games Modding Documentation — the official Unturned modding documentation, including the current required Unity version.
• Unturned on Steam — the game itself.

Appendix A: Player.log signatures for the fifteen causes

Cause	Log signature
1. Wrong target platform	AssetBundle was not built for this platform
2. Missing English.dat	No localization for asset
3. Duplicate GUID	Duplicate GUID
4. Reserved ID range	Cannot register asset with reserved ID
5. meta.dat malformed	Skipping folder or absence of any log entry for the mod
6. Wrong encoding	.dat parse error
7. Unity version mismatch	Could not load AssetBundle or AssetBundle version mismatch
8. Folder not enumerated	Absence of any log entry for the mod
9. Server-side load	Client-side: Cannot resolve asset reference
10. Antivirus block	Access denied or Could not open file
11. Workshop incomplete	Absence of any log entry; files missing from Workshop folder
12. Plugin conflict	No Unturned log signature; check plugin logs
13. Renamed assets	Asset not found or GUID mismatch
14. Bundle missing	Failed to find bundle
15. Path length	Intermittent Could not open file

Appendix B: cohort-validated mod folder template

The folder structure below is the cohort-recommended layout for a single Unturned content mod. Following the template prevents Causes 5, 8, 13, and 15.

MyMod/
├── meta.dat                       <-- mod identification
├── README.md                      <-- modder-facing notes (not loaded by game)
├── MyMod.bundle                   <-- master bundle output
├── Items/
│   ├── SteelSword/
│   │   ├── SteelSword.dat
│   │   └── English.dat
│   └── ReinforcedArmor/
│       ├── ReinforcedArmor.dat
│       └── English.dat
└── Vehicles/
    └── ArmoredJeep/
        ├── ArmoredJeep.dat
        └── English.dat

The folder structure has three levels of nesting maximum (MyMod/Items/SteelSword/), which keeps path lengths under the Windows limit. Every item folder contains both the asset .dat and the English.dat, which prevents Cause 2. The bundle file is at the mod root, where the asset .dat files reference it without complex path prefixes.

Appendix C: cohort case studies

Case study 1: the OSX-target bundle

A new cohort member developed an item mod on a MacBook with the Unity editor configured for StandaloneOSX as the default target. They built the bundle, copied it into the Windows partition's Unturned folder via the dual-boot shared drive, and launched the game. The mod folder was enumerated; the bundle failed to load. The Player.log showed "AssetBundle was not built for this platform" against the bundle file.

The fix was Method 1: switch the Unity Build Settings to Windows x86_64 and rebuild. The cohort recommendation that resulted from the case study is to add a Build Settings check to any cross-platform development workflow. The MacBook can develop the mod's source but the bundle must always be built with the Windows target before deployment.

Case study 2: the duplicate GUID between two friends' mods

Two long-tenure cohort members independently shipped item mods that used the same GUID for a weapon. The collision was not detected until a server admin installed both mods on the same server; one mod's weapon overrode the other's, with both authors confused as to why.

The fix was for one of the authors to change the GUID and republish. The cohort recommendation that resulted from the case study is to publish GUIDs to the cohort's public GUID registry at the time of mod release; subsequent modders can search the registry to confirm uniqueness before publishing.

Case study 3: the UTF-8 BOM that hid in meta.dat

A mid-tenure cohort member opened meta.dat in Notepad to make a small edit, saved the file, and pushed the change to their published mod. The next subscriber to the mod found the entire mod no longer loaded. The cohort diagnosed the failure as Cause 6: Notepad had silently re-saved the file with UTF-8 BOM, and the BOM bytes caused the parser to fail on the first line.

The fix was Method 6: open the file in Notepad++, convert to ANSI, save. The cohort recommendation that resulted from the case study is to never use Notepad for .dat files. Notepad++ is the cohort's recommended editor; it shows the encoding explicitly and resists the silent BOM injection that Notepad performs by default.

Case study 4: the antivirus quarantine

A new cohort member subscribed to a popular Unturned mod and found the mod did not load. The Workshop showed the subscription as complete. The Workshop content folder was empty. The cohort diagnosis identified Cause 10: the modder's antivirus had heuristically flagged the mod's bundle as suspicious and quarantined it on download.

The fix was Method 10: add an antivirus exclusion for the Workshop content folder, restore the quarantined files. The cohort recommendation that resulted from the case study is to configure antivirus exclusions for the Unturned install folder during initial machine setup, before subscribing to any Workshop content.

Case study 5: the path-length truncation in a deeply nested mod

A long-tenure cohort member organised their large content mod under a deeply nested folder structure (MyMod/Items/Weapons/Melee/OneHanded/Swords/Steel/SteelLongsword/). The Steam Workshop install path placed the mod's longest files past the Windows 260-character limit. The mod partially loaded: some items appeared while others were intermittently missing.

The fix was Method 15: flatten the folder structure to three levels of nesting (MyMod/Items/Steel-Longsword/). The cohort recommendation that resulted from the case study is to enforce a three-level nesting maximum on all cohort mods, validated by a pre-publish lint script.

Appendix D: pre-publish checklist

The cohort's pre-publish checklist runs before every mod release. The checklist takes approximately five minutes and catches the load-failure causes documented in this article.

Step	Check	Pass criteria
1	Bundle build target	Windows x86_64
2	Unity version	Matches Smartly Dressed Games' current requirement
3	meta.dat present	Yes, in mod root
4	meta.dat encoding	ANSI
5	meta.dat parses	Test load in local install
6	Every item has English.dat	Confirmed by file walk
7	Every .dat is ANSI encoded	Confirmed by file walk
8	No reserved-range IDs	All IDs > 2000
9	GUIDs unique within mod	Confirmed by registry script
10	GUIDs unique cross-mod	Confirmed against cohort registry
11	Bundle file present	At expected path
12	Bundle GUIDs match asset references	Confirmed by inspector
13	Path length under limit	Longest path < 200 characters
14	Test load in local install	Mod loads, items appear
15	Test load on dedicated server	Mod loads, client sees items

A modder who runs the pre-publish checklist before every release reduces the rate of post-release load failures to approximately 4 percent in the cohort survey data, compared to approximately 38 percent for releases without the checklist.

Closing note

Mod-load failures are the single highest-volume troubleshooting category in the 57 Studios cohort survey, accounting for approximately 32 percent of all troubleshooting requests across the 2024 and 2025 cohort years. The fifteen-cause framework documented in this article covers the overwhelming majority of cohort-reported failures.

A modder who internalises the diagnostic flow and the cause-by-symptom lookup can typically resolve a mod-load failure within fifteen to thirty minutes from the first symptom. The diagnostic flow is the cohort's recommended approach for new modders; the cause-by-symptom lookup becomes faster as the modder gains familiarity with the fifteen causes.

The pre-publish checklist in Appendix D is the cohort's strongest defensive practice against mod-load failures. The five-minute cost of the checklist is much lower than the documented cost of recovering from a published mod that fails to load for subscribers, which averages approximately three to five hours per incident (including diagnosis, fix, republish, and subscriber re-download).

Next steps

If the mod loads but its items do not appear in-game, continue to Items Missing in Game. If the mod loads but conflicts with another mod's content, continue to GUID Conflicts Between Mods. Return to the section overview at Troubleshooting for a list of all articles in this section.