Mod Error Codes (EB1ModError)¶
This document summarizes the error codes and their causes when mod inspection (compatibility check) fails.
Definition location
Source/BlueModManager/ModSystem/B1Mod.h
Fatal error
When a Fatal error (ConfigError) occurs, the mod is blocked from Manifest saving and activation.
1.Error code list¶
| Code | Value | Display name | Fatal |
|---|---|---|---|
ConfigError |
1 << 0 |
Config Error | :material-alert-circle:{ .fatal } Fatal |
PakFileNotFound |
1 << 1 |
(No popup) | — |
UcasFileNotFound |
1 << 2 |
(No popup) | — |
UtocFileNotFound |
1 << 3 |
(No popup) | — |
PakMountError |
1 << 4 |
(No popup) | — |
PakUnMountError |
1 << 5 |
(No popup) | — |
DataPatchError |
1 << 6 |
Data Error | — |
ShaderCompatibilityError |
1 << 7 |
Shader Compatibility Error | — |
AssetCompatibilityError |
1 << 8 |
Asset Compatibility Error | — |
LuaScriptError |
1 << 9 |
Lua Script Error | — |
OldModKitVersion |
1 << 10 |
Old ModKit Version | — |
2.Detailed descriptions¶
ConfigError
Cause: The mod's base configuration file cannot be loaded.
| Trigger | Details |
|---|---|
mod_manifest.json load/parse failure |
Manifest file is corrupted or does not exist |
| Mod name and project name mismatch | Name in manifest differs from .uplugin file name |
.uplugin file load/parse failure |
Plugin descriptor is corrupted or does not exist |
Inspection location
B1Mod::LoadFromManifest()
PakFileNotFound / UcasFileNotFound / UtocFileNotFound
Cause: Mod package file structure validation failed.
| Error | Details |
|---|---|
PakFileNotFound |
.pak file does not exist |
UcasFileNotFound |
.ucas file does not exist |
UtocFileNotFound |
.utoc file does not exist |
Inspection location
B1Mod::TestFileStructure()
PakMountError / PakUnMountError
Cause: Pak file mount/unmount runtime failure.
| Error | Details |
|---|---|
PakMountError |
FPakPlatformFile::Mount() call failed — pak file is corrupted or locked by another process |
PakUnMountError |
FPakPlatformFile::Unmount() call failed — already unmounted or references remain |
Inspection location
B1Mod::Mount(), B1Mod::Unmount()
DataPatchError
Cause: An error occurred while processing the mod's JSON data patch.
| Scenario | Details |
|---|---|
| Source JSON not found | Cannot find the original data (StructTag-based) to patch |
| Named source JSON not found | Cannot find the specified named data source |
| Invalid JSON value | Patch descriptor contains an invalid JSON value |
| Patch descriptor load failure | Failed to load FModPatchDescriptor |
| Patch application error | Patch commands (Add/Remove/Replace, etc.) failed to apply to target data |
| Patch result deserialization failure | Failed to convert patched JSON to struct |
Inspection location
B1ModdingTool_DataPatch::OnTest() → CollectModdingData() / BuildModdedJson()
ShaderCompatibilityError
Cause: Shaders included in the mod are incompatible with the current game build.
Reserved code
There are currently no direct SetError calls for this error in the codebase.
It is only registered in the error report mapping and reserved for future shader compatibility validation.
AssetCompatibilityError
Cause: Mod assets are incompatible with the current game build.
| Scenario | Inspection tool | Details |
|---|---|---|
| Asset Hash JSON missing | B1ModdingTool_Asset |
Contains MPC assets but hash file is missing |
| MPC GUID mismatch | B1ModdingTool_Asset |
MaterialParameterCollection StateId differs from the game |
| MPC path invalid/load failure | B1ModdingTool_Asset |
Asset hash JSON contains an invalid MPC path |
| Material structure hash mismatch | B1ModdingTool_Asset |
Material parameter structure has changed (e.g. game update) |
| Material path invalid/load failure | B1ModdingTool_Asset |
Material asset does not exist |
| MFI hash mismatch | B1ModdingTool_Asset |
MaterialFunctionInstance structure has changed |
| MFI path invalid/load failure | B1ModdingTool_Asset |
MFI asset does not exist |
| DA exists as pak asset | B1ModdingTool_DataAsset |
DataAsset is packaged as a pak asset instead of JSON |
| AnimMontage Notify class load failure | B1ModdingTool_AnimMontage |
Notify class referenced by montage does not exist |
| AnimMontage Notify property mismatch | B1ModdingTool_AnimMontage |
Notify class properties differ from the game (added/removed) |
LuaScriptError
Cause: Lua script validation failed for the mod.
| Scenario | Details |
|---|---|
.lua/.luapak mixed usage |
Both formats used simultaneously in one mod |
| Static analysis (luacheck) execution failure | Error occurred while running the analysis tool |
| Analysis result file missing | Analysis output file was not generated |
| Analysis result parse failure | Output JSON file has an invalid format |
| Lua diagnostic error detected | Static analysis found error-level diagnostic results |
Inspection location
B1ModdingTool_LuaScript::OnTest() → RunLuaStaticAnalysis()
- OldModKitVersion
Cause: The mod was built with an outdated ModKit version.
| Scenario | Details |
|---|---|
| ModKit changelist below minimum | The second digit (changelist) of the mod version is below the minimum requirement (11246) |
This check only applies to UE 5.6+ builds.
Inspection location
B1ModdingTool_Version::OnTest()
3.Mod states (EB1ModState)¶
| State | Value | Description |
|---|---|---|
Active |
1 << 0 |
Activated and applied to the game |
Inspecting |
1 << 2 |
Compatibility check in progress |
Unreachable |
1 << 3 |
Mod directory is inaccessible |
Broken |
1 << 4 |
Structure is corrupted |
RuntimeError |
1 << 5 |
Deactivated due to inspection failure |
AddedInGame |
1 << 6 |
Mod added in-game |