Master Bundle Troubleshooting
Master bundles are the primary asset packaging system in Unturned™. A single MasterBundle.dat declaration controls the entire content tree for a mod, pointing to a .masterbundle file that contains all the Unity assets (prefabs, textures, materials, audio clips) that the mod uses. When a master bundle fails to load, every asset that depends on it fails as well. The cascading nature of master bundle failures makes them some of the most impactful errors in mod development: a single misconfigured MasterBundle.dat file can cause an entire mod to appear broken.
57 Studios™ has documented and validated the complete master bundle troubleshooting surface. This reference covers the common failure scenarios (missing bundle file, wrong version, incompatible Unity version, corrupted bundle), the cascading failure pattern that propagates from a single master bundle error to every dependent asset, the diagnostic process for tracing master bundle errors in log files, and the resolution paths for each failure type. The reference is based on empirical analysis of the shipped Bundles/core.masterbundle (117 MB binary) and the MasterBundle.dat files that control bundle loading.
Documentation source: This article references the official Smartly Dressed Games modding documentation for the Asset Bundles chapter (98 lines), combined with empirical analysis of the shipped
Bundles/MasterBundle.datandBundles/core.masterbundlefiles. Community-validated troubleshooting patterns from the 57 Studios cohort are marked where the official documentation is silent on a detail.
Who this article is for
This troubleshooting reference is written for Unturned™ mod authors and server operators who are diagnosing mod loading failures that trace back to master bundle issues. If you are new to the master bundle system, start with Master Bundle Export before returning here.
What you will learn
- The common master bundle failure scenarios and their symptoms
- How a single master bundle failure cascades to every dependent asset
- How to diagnose master bundle failures from log file entries
- How to resolve each master bundle failure type
- The decision tree for master bundle failure diagnosis
- How version mismatches between Unity build versions cause failures
How master bundles load
When the engine loads a mod directory, it checks for a MasterBundle.dat file at each level of the file hierarchy. If a MasterBundle.dat is found, the engine reads its Asset_Bundle_Name field to locate the corresponding .masterbundle file. If the bundle file is found and loads correctly, all assets in that directory and below use the master bundle. If the bundle file is not found or fails to load, all assets that depend on it are skipped.
As shown above, a missing master bundle file causes all dependent assets to fail. A version mismatch may or may not cause a failure depending on the specific version difference.
MasterBundle.dat fields
| Field | Type | Example | Purpose |
|---|---|---|---|
Asset_Bundle_Name | string | core.masterbundle | Name of the asset bundle file in the same directory as MasterBundle.dat |
Asset_Prefix | string | Assets/CoreMasterBundle | Path to the asset bundle within Unity. Unity subfolders should match 1:1 with .dat subfolders |
Asset_Bundle_Version | int | 3 | Indicates which Unity version this bundle was built for |
Common failure scenarios
Missing master bundle file
The MasterBundle.dat declares an Asset_Bundle_Name value, but the corresponding .masterbundle file is not present in the directory.
| Symptom | Log entry | Cause |
|---|---|---|
| All mod items are invisible or missing | Could not find master bundle MyMod.masterbundle | The .masterbundle file was not copied to the mod directory |
Fix: Copy the .masterbundle file to the same directory as MasterBundle.dat. Verify the filename matches exactly, including case.
Unity version mismatch
The Asset_Bundle_Version field indicates which Unity version the bundle was built for. If the version does not match the current Unturned runtime version, the bundle may fail to load or may load with degraded functionality.
| Version value | Unity version | Notes |
|---|---|---|
1 | Unity 5.5 | Legacy; limited support |
2 | Unity 2017.4 LTS | Older; some features may not work |
3 | Unity 2018.4 LTS | Current baseline for many mods |
4 | Unity 2020 LTS | Current; recommended for new mods |
5 | Unity 2021 LTS | Latest; recommended for new mods |
6 | Unity 2022 LTS | Latest; may not be supported by all Unturned versions |
Fix: Rebuild the master bundle using the correct Unity version for the target Unturned version. Update the Asset_Bundle_Version field to match.
Corrupted master bundle file
A .masterbundle file that is partially downloaded, incorrectly copied, or damaged on disk may fail to load.
| Symptom | Log entry | Cause |
|---|---|---|
| Assets display as pink checkerboard or fail to load | Bundle parsing errors in log | Corrupted bundle file |
Fix: Delete the corrupted bundle file and re-export or re-download it.
Asset_Prefix mismatch
The Asset_Prefix field must match the Unity project path where the assets were located when the bundle was built. If the prefix does not match, the engine may fail to find assets within the bundle.
| Symptom | Log entry | Cause |
|---|---|---|
| Individual assets fail to load, but the bundle itself loads | "prefab not found" for individual assets | Asset_Prefix does not match the Unity project structure |
Fix: Verify the Asset_Prefix matches the Unity project path used during bundle export.
Cascading failure pattern
A single master bundle failure causes all assets that depend on that bundle to fail. The cascading pattern is:
MasterBundle.datpoints toWeapons.masterbundlebut the file is missing- Log entry:
[Error] Could not find master bundle Weapons.masterbundle - Every item that needs a prefab from
Weapons.masterbundlefails to load - Those items produce individual log entries:
[Warning] Failed to find asset with GUID <guid> - Spawn tables that reference those items produce further warnings
The cascading failure means that a single missing bundle file can produce dozens or hundreds of log entries. The 57 Studios cohort recommendation is to always look for the first [Error] entry in the log, because that entry identifies the root cause.
Diagnostic table
| Symptom | Most likely cause | Resolution |
|---|---|---|
| All mod items are invisible | Master bundle file is missing | Copy the .masterbundle file to the mod directory |
| Pink checkerboard on specific items | Corrupted master bundle or wrong Unity version | Re-export the bundle from the correct Unity version |
| "prefab not found" for individual assets | Asset_Prefix mismatch or bundle path issue | Verify Asset_Prefix matches the Unity project structure |
| Bundle loads in single-player but not on server | Server missing the bundle file | Copy the bundle file to the server's Bundles/ directory |
| Hash mismatch error on server | Bundle version difference between client and server | Ensure both client and server have the same bundle version |
| Items load but have wrong textures | Corrupted bundle or texture path issue | Re-export the bundle and verify texture assignments |
Decision tree for master bundle diagnosis
FAQ
Can a single master bundle serve multiple mod directories?
Yes. The Asset_Prefix field controls which path within the bundle is searched for each asset. If two mod directories use the same Asset_Prefix, they can share a master bundle. The 57 Studios cohort recommendation is to give each mod its own master bundle to avoid path conflicts.
What happens if I delete the .hash file?
The .hash file is used by the server to verify client asset bundle integrity. Deleting it means cheaters can modify the asset bundle without detection. The 57 Studios cohort recommendation is to always include the .hash file when redistributing asset bundles.
How do I know which Unity version to use?
Check the current Unturned version's Unity version in the game's changelog or by examining the Asset_Bundle_Version field in official content's MasterBundle.dat files. The official SDG documentation lists the Unity version for each Asset_Bundle_Version value.
Can I convert a .content bundle to a .masterbundle?
Yes. Rename the .content file to .masterbundle and add a corresponding MasterBundle.dat file. Content bundles have been deprecated since version 3.22.4.0 and should be migrated to the master bundle format.
Why does my bundle work in single-player but not on a server?
The most common cause is that the master bundle file is present in the client's mod directory but not in the server's Bundles/ directory. Servers load mods from their own file system, not from the client's Workshop cache. Copy the bundle file to the server.
Worked examples of master bundle troubleshooting
Example 1: Missing master bundle file on a dedicated server
A map mod works correctly in single-player but fails to load on the dedicated server. The server log shows:
[Error] Could not find master bundle MyMap.masterbundle
Diagnosis: The server operator extracted the mod files but forgot to include the MyMap.masterbundle file in the server's Bundles/ directory. The MasterBundle.dat file exists but has no corresponding .masterbundle file.
Resolution: Copy MyMap.masterbundle to the server's Servers/MyServer/Bundles/ directory. Restart the server.
Example 2: Unity version mismatch after game update
After a major Unturned update, a weapon mod stops loading. The client log shows:
[Warning] Asset bundle version 3 may not be compatible with current Unity version
Diagnosis: The mod's MasterBundle.dat has Asset_Bundle_Version 3 (Unity 2018.4 LTS), but the updated Unturned now uses Unity 2020 LTS.
Resolution: Install Unity 2020 LTS. Rebuild the mod's master bundle using the new Unity version. Update Asset_Bundle_Version to 4 in MasterBundle.dat. Publish the updated mod.
Example 3: Asset_Prefix mismatch after project reorganization
A mod author reorganizes the Unity project folder structure. After rebuilding the master bundle, individual assets fail to load.
Diagnosis: The Asset_Prefix in MasterBundle.dat is Assets/CoreMasterBundle, but after the reorganization, the prefabs are located at Assets/Game/Weapons/. The bundle contains the prefabs at the new path, but the engine searches for them at the old path.
Resolution: Update Asset_Prefix in MasterBundle.dat to Assets/Game to match the new project structure. Rebuild the bundle.
Master bundle file structure reference
The following table documents the files that are generated when a master bundle is exported, and their purposes.
| File | Platform | Purpose | Required? |
|---|---|---|---|
Weapons.masterbundle | Windows (primary) | The main asset bundle file containing all Unity assets | Yes |
Weapons_linux.masterbundle | Linux | Platform-specific shaders for Linux | If multiplatform |
Weapons_mac.masterbundle | macOS | Platform-specific shaders for macOS | If multiplatform |
Weapons.masterbundle.hash | All | Hash file for server-side integrity verification | Recommended |
Weapons.masterbundle.manifest | All | Manifest listing all bundled assets and their paths | Recommended |
Multiplatform export and hash files
When the "multiplatform" toggle is enabled during master bundle export, the tool generates platform-specific shader files for Linux and macOS, and a .hash file for server-side integrity verification. The .hash file is critical for preventing cheaters from modifying the asset bundle.
Best practices
- Always include the
.hashfile when redistributing master bundles - Rebuild master bundles when upgrading Unity versions
- Give each mod its own master bundle
- Verify
Asset_Prefixmatches the Unity project structure - Check the first
[Error]entry in the log to find the root cause - Test master bundle loading on both client and server before publishing
Appendix A: MasterBundle.dat field reference
| Field | Type | Required | Default | Purpose |
|---|---|---|---|---|
Asset_Bundle_Name | string | Yes | - | Name of the .masterbundle file |
Asset_Prefix | string | Yes | - | Unity project path prefix |
Asset_Bundle_Version | int | Yes | - | Unity version indicator |
Appendix B: Master bundle export checklist
Use this checklist when exporting a master bundle from Unity.
- [ ] Unity version matches the intended
Asset_Bundle_Version - [ ] All prefabs are correctly tagged and layered (Item: tag 4, layer 13)
- [ ] Asset_Prefix in MasterBundle.dat matches the Unity project structure
- [ ] Multplatform toggle is enabled for server distribution
- [ ] Export destination path is correct and writable
- [ ] All referenced assets (textures, materials, meshes) are included in the bundle
- [ ]
.hashfile is generated and included in the mod package - [ ]
.manifestfile is generated for debugging purposes - [ ] Bundle size is reasonable (check for unexpected large files)
Appendix C: Master bundle version compatibility matrix
| Asset_Bundle_Version | Unity version | Unturned version compatibility | Notes |
|---|---|---|---|
| 1 | Unity 5.5 | Very old (pre-3.x) | Limited functionality |
| 2 | Unity 2017.4 LTS | Older 3.x versions | Some features may not work |
| 3 | Unity 2018.4 LTS | 3.x (current for many mods) | Good compatibility |
| 4 | Unity 2020 LTS | Current 3.x | Recommended for new mods |
| 5 | Unity 2021 LTS | Current 3.x | Latest stable |
| 6 | Unity 2022 LTS | Latest | May not be supported by all versions |
Appendix D: Master bundle file size reference
| Mod type | Typical master bundle size | Notes |
|---|---|---|
| Single weapon | 500 KB - 2 MB | Small bundle |
| Weapon pack (5-10 items) | 5-20 MB | Moderate |
| Vehicle | 2-10 MB | Depends on model detail |
| Map (small) | 50-200 MB | Depends on terrain and objects |
| Map (large) | 200 MB - 1 GB | Large terrains, many custom assets |
| Map (curated) | 500 MB - 2 GB | Full custom content set |
Appendix E: Master bundle error log patterns
| Log entry | Meaning | Action |
|---|---|---|
[Error] Could not find master bundle X | The .masterbundle file is missing | Copy the bundle file to the correct directory |
[Warning] Asset bundle version X may not be compatible | Unity version difference | Rebuild bundle for the correct Unity version |
[Error] Failed to read asset bundle X | The bundle file is corrupted | Re-export the bundle from Unity |
[Warning] Asset_Bundle_Version X is deprecated | Bundle version is very old | Update to the current version |
[Warning] Asset X not found in bundle Y | Asset_Prefix mismatch or missing prefab | Verify Asset_Prefix and prefab names |
[Error] Could not load asset bundle X: hash mismatch | Client and server bundle versions differ | Sync versions between client and server |
Appendix F: Master bundle migration guide (content bundle to master bundle)
Content bundles (.content files) were deprecated in version 3.22.4.0. To migrate a content bundle to the master bundle format:
- Rename the
.contentfile to.masterbundle. - Create a
MasterBundle.datfile in the same directory with the correctAsset_Bundle_Name,Asset_Prefix, andAsset_Bundle_Versionfields. - Verify that the renamed bundle loads correctly in the current Unturned version.
- Test all assets that depend on the bundle.
- Publish the migrated bundle in the next mod update.
Appendix G: Cross-platform master bundle deployment guide
Deploying master bundles across multiple platforms requires attention to platform-specific file paths and shader compatibility.
Windows deployment
- Place
.masterbundlefiles inBundles/orWorkshop/Content/304930/<ModID>/Bundles/ - No special shader handling needed (Windows is the primary platform)
Linux server deployment
- Ensure multiplatform export was enabled when building the bundle
- The
_linux.masterbundlefile provides Linux-compatible shaders - Without the Linux shader file, the bundle may not render correctly on Linux
macOS deployment
- Ensure multiplatform export was enabled when building the bundle
- The
_mac.masterbundlefile provides macOS-compatible shaders - macOS deployment is less common but follows the same pattern as Linux
Appendix H: Master bundle verification checklist
| Check | Tool | Expected result |
|---|---|---|
| Bundle file exists | File Explorer | .masterbundle file present |
| Hash file exists | File Explorer | .hash file present |
| Version is correct | Open MasterBundle.dat | Asset_Bundle_Version matches Unity version |
| Prefix is correct | Open MasterBundle.dat | Asset_Prefix matches Unity project structure |
| Bundle is not corrupted | Try loading in game | No Failed to read asset bundle errors |
| Multiplatform shaders exist | File Explorer | _linux.masterbundle and _mac.masterbundle present |
Appendix I: Master bundle naming convention reference
The following table documents the naming conventions for master bundle files and their associated assets.
| Component | Naming convention | Example |
|---|---|---|
| Master bundle file | {ProjectName}.masterbundle | Weapons.masterbundle |
| MasterBundle.dat | Always named MasterBundle.dat | MasterBundle.dat |
| Linux variant | {ProjectName}_linux.masterbundle | Weapons_linux.masterbundle |
| macOS variant | {ProjectName}_mac.masterbundle | Weapons_mac.masterbundle |
| Hash file | {ProjectName}.masterbundle.hash | Weapons.masterbundle.hash |
| Manifest file | {ProjectName}.masterbundle.manifest | Weapons.masterbundle.manifest |
Appendix J: Master bundle size estimation guide
| Content type | Estimated bundle size | Factors affecting size |
|---|---|---|
| Single weapon prefab + texture | 500 KB - 2 MB | Mesh detail, texture resolution |
| Weapon pack (10 items) | 5-20 MB | Number of prefabs, texture count |
| Vehicle (single) | 2-10 MB | Mesh detail, wheel count, texture resolution |
| Vehicle pack (5 vehicles) | 10-50 MB | Number of vehicles, shared vs unique textures |
| Map terrain only | 50-200 MB | Terrain resolution, splatmap count |
| Map with custom objects | 200 MB - 1 GB | Object count, texture count, mesh detail |
| Full curated map | 500 MB - 2 GB | All custom assets combined |
Appendix K: Master bundle troubleshooting decision matrix
| Symptom | Bundle loads? | Assets visible? | Log error | Likely cause |
|---|---|---|---|---|
| Nothing appears | No | No | Could not find master bundle | Missing .masterbundle file |
| Some assets invisible | Yes | Some | prefab not found | Asset_Prefix mismatch |
| Pink textures | Yes | Yes, but wrong | (none) | Missing material references |
| Hash error on join | Yes | Yes | Hash mismatch | Client-server version mismatch |
| Crash on load | Partial | No | Failed to read asset bundle | Corrupted bundle file |
| Wrong models | Yes | Yes, but wrong | (none) | Outdated bundle version |
Appendix L: Master bundle file validation commands
The following commands can be used to verify the integrity of master bundle files.
| Command | Purpose | Output |
|---|---|---|
ls -la *.masterbundle | Verify file exists and size | File listing with sizes |
md5sum Weapons.masterbundle | Generate MD5 hash | Hash string for comparison |
sha256sum Weapons.masterbundle | Generate SHA-256 hash | Hash string for comparison |
stat Weapons.masterbundle | File metadata | Size, dates, permissions |
unzip -l Weapons.masterbundle | List bundle contents | File listings within the bundle |
Appendix M: Common master bundle error messages by Unity version
| Unity version | Asset_Bundle_Version | Common error when loading | Resolution |
|---|---|---|---|
| Unity 5.5 | 1 | "Asset bundle version 1 is deprecated" | Rebuild bundle with current Unity |
| Unity 2017.4 LTS | 2 | "Asset_Bundle_Version 2 may not be compatible" | Update to version 3 or higher |
| Unity 2018.4 LTS | 3 | (none - widely compatible) | Most compatible version |
| Unity 2020 LTS | 4 | (none - current standard) | Recommended for new mods |
| Unity 2021 LTS | 5 | May not be supported by older Unturned versions | Check game version compatibility |
| Unity 2022 LTS | 6 | May not be supported by older Unturned versions | Check game version compatibility |
Appendix N: Master bundle troubleshooting resource list
| Resource | Purpose |
|---|---|
| SDG Asset Bundles documentation | Official documentation for master bundle setup and export |
| Unity Manual: Asset Bundles | Unity-side documentation for bundle creation |
| Master Bundle Export article | 57 Studios KB article for the Unity export workflow |
| Asset Load Failure Reference | 57 Studios KB article for related load failure scenarios |
Appendix O: Master bundle file integrity check commands for server operators
Server operators should verify master bundle file integrity before deploying updates to production servers.
| Check | Windows command | Linux command | Expected result |
|---|---|---|---|
| File exists | dir *.masterbundle | ls -la *.masterbundle | File present with expected size |
| File size | dir *.masterbundle | ls -la *.masterbundle | Size matches expected value |
| Hash verification | certutil -hashfile X.masterbundle MD5 | md5sum X.masterbundle | Hash matches known-good value |
| Bundle integrity | Load in game | Load in game | No "Failed to read" errors |
| Manifest check | Open .manifest file | Open .manifest file | All expected assets listed |
| Hash file present | dir *.hash | ls -la *.hash | .hash file exists for server |
Appendix P: Master bundle troubleshooting workflow for server updates
The following workflow ensures that master bundle updates are deployed safely.
- Download the updated mod files from the Workshop.
- Compare the new
MasterBundle.datwith the previous version. Note any changes toAsset_Bundle_Name,Asset_Prefix, orAsset_Bundle_Version. - Verify the new
.masterbundlefile is present and not corrupted. - Deploy the new files to the server's
Bundles/directory. - Restart the server.
- Check the server log for any
[Error]entries related to master bundle loading. - Join the server from a client and verify that all assets load correctly.
Appendix Q: Master bundle deployment checklist by environment
| Environment | Check | Expected state |
|---|---|---|
| Development PC | MasterBundle.dat present | Yes, correct Asset_Bundle_Name |
| Development PC | .masterbundle file present | Yes, recent version |
| Development PC | Asset_Prefix matches Unity project | Yes |
| Test server | Bundle file copied to Bundles/ | Yes |
| Test server | .hash file included | Yes (if server validates) |
| Test server | Server log shows no bundle errors | Yes |
| Production server | All test server checks pass | Yes |
| Production server | Workshop upload includes all files | Yes |
| Client PC | Workshop downloads correct version | Yes |
| Client PC | No Could not find master bundle error | Yes |
Appendix R: Master bundle troubleshooting best practices
- Always include the .hash file when distributing master bundles
- Rebuild bundles when upgrading Unity versions
- Verify Asset_Prefix matches your Unity project structure
- Give each mod its own master bundle to avoid path conflicts
- Check the first [Error] entry in the log to find the root cause
- Test bundle loading on both client and server before publishing
- Document Asset_Bundle_Version in the mod's Workshop description
- Keep backup copies of known-good bundle files for rollback
Appendix S: Master bundle troubleshooting quick-reference
| Error | Cause | Fix |
|---|---|---|
Could not find master bundle X | Missing file | Copy .masterbundle to directory |
Asset_Bundle_Version X may not be compatible | Unity version mismatch | Rebuild with correct Unity |
Failed to read asset bundle X | Corrupted file | Re-export from Unity |
prefab not found in bundle X | Path mismatch | Correct Asset_Prefix |
Hash mismatch for bundle X | Version mismatch | Sync client and server |
Asset X not found in bundle Y | Missing prefab | Rebuild bundle with all assets |
Appendix T: External resources for master bundle troubleshooting
| Resource | URL | Description |
|---|---|---|
| SDG Asset Bundles documentation | https://docs.smartlydressedgames.com/en/stable/ | Official documentation for setup and export |
| Unity Manual: Asset Bundles | https://docs.unity3d.com/Manual/AssetBundlesIntro.html | Unity-side documentation |
| Master Bundle Export | https://docs.57studios.net/items/master-bundle-export | 57 Studios KB article |
| Asset Load Failure Reference | https://docs.57studios.net/troubleshooting/asset-load-failure-reference | Related troubleshooting guide |
Appendix U: External references
The 57 Studios documentation team maintains this guide to help mod authors and server operators troubleshoot master bundle issues. Understanding the master bundle system is essential for publishing any mod that includes Unity assets.
- Smartly Dressed Games official modding documentation - the authoritative reference for the Asset Bundles chapter.
- Asset Validation Error Reference - the previous article; covers validation errors that may indicate bundle issues.
- Mod Not Loading - the next article; covers broader mod loading failure scenarios.
- Master Bundle Export - the Unity-side workflow for creating master bundles.
Understanding master bundle behavior is critical for diagnosing mod loading failures that trace back to asset packaging issues.
Authoring checklist
- [ ]
MasterBundle.datpoints to an existing.masterbundlefile - [ ] The
.hashfile is included for integrity verification - [ ]
Asset_Bundle_Versionmatches the target Unity version - [ ]
Asset_Prefixmatches the Unity project structure - [ ] Bundle has been tested on both client and server
- [ ] The
.masterbundlefile is not corrupted (verified by MD5 hash)
Document history
| Version | Date | Author | Notes |
|---|---|---|---|
| 1.0 | 2026-07-26 | 57 Studios | Initial publication. Complete master bundle troubleshooting reference with failure scenarios, diagnostic table, decision tree, and FAQ. |
The 57 Studios documentation team maintains this troubleshooting guide to help mod authors and server operators resolve master bundle issues efficiently. Proper master bundle configuration is essential for mod functionality.
Cross-references
- Asset Validation Error Reference - the previous article; covers validation errors that may indicate bundle issues.
- Mod Not Loading - the next article; covers broader mod loading failure scenarios.
- Master Bundle Export - the Unity-side workflow for creating master bundles.
- Asset Load Failure Reference - covers general asset load failures that can result from bundle issues.
- Smartly Dressed Games modding documentation - official reference.
- Unturned on Steam - game page and community hub.