Skip to main content
This guide covers common issues you may encounter while using BD2 Mod Manager and how to resolve them.

​
Common issues

This is a false positive caused by how PyInstaller packages Python applications into executables. The program does not contain any malware.

​
Why this happens

PyInstaller bundles the Python interpreter and all dependencies into a single executable. Antivirus software often flags this behavior as suspicious because it’s similar to how some malware packers work.

​
Solutions

  1. Add an exception in your antivirus software for BD2ModManager.exe
  2. Use the Full.zip version instead of the standalone .exe (less likely to trigger false positives)
  3. Build from source if you want to verify the code yourself:
    • Download the source code from GitHub
    • Review the code to ensure it’s safe
    • Build the executable using the provided build scripts
The source code is publicly available on GitHub for transparency. You can inspect every line of code before running it.
This error occurs when BD2 Mod Manager cannot locate the Brown Dust 2 installation.

​
Error message

GameDirectoryNotSetError: Game path is not set. Please set the game path first.
or
GameNotFoundError: Game executable 'BrownDust II.exe' not found in directory: [path]

​
Solutions

  1. Set the game directory manually:
    • Click the settings or browse button
    • Navigate to your Brown Dust 2 installation folder
    • Select the folder containing BrownDust II.exe
  2. Typical installation paths: 
    F:\Neowiz\Browndust2\Browndust2_10000001
C:\Games\Browndust2\Browndust2_10000001
  3. Auto-detection: The mod manager attempts to locate the game using the Windows registry: 
    key = winreg.OpenKey(
    winreg.HKEY_CURRENT_USER,
    r"Software\Neowiz\Browndust2Starter\10000001"
)
path, _ = winreg.QueryValueEx(key, "path")
If auto-detection fails, you must set the path manually.
This error indicates that the BrownDustX mod loader is not installed in your game directory.

​
Error message

BrownDustXNotInstalled: BrownDustX is not installed!

​
What is BrownDustX?

BrownDustX is a mod loader required for mods to work in Brown Dust 2. BD2 Mod Manager syncs mods to the BrownDustX mods folder.

​
Solutions

  1. Install BrownDustX:
    • Download BrownDustX from the official source
    • Install it to your Brown Dust 2 game directory
    • Verify the installation by checking for this file: 
      [Game Directory]\BepInEx\plugins\BrownDustX\lynesth.bd2.browndustx.dll
  2. Verify the game path: Make sure you’ve selected the correct game directory
BD2 Mod Manager cannot sync mods without BrownDustX installed. All sync operations require BrownDustX to be present.
This error occurs when attempting to use symlink mode without administrator rights.

​
Error message

AdminRequiredError: Administrator privileges are required to use symlinks.

​
Why admin rights are needed

Creating symbolic links on Windows requires administrator privileges for security reasons. This is a Windows limitation, not a mod manager restriction.

​
Solutions

  1. Run as administrator:
    • Right-click BD2ModManager.exe
    • Select “Run as administrator”
    • Approve the UAC prompt
  2. Use copy mode instead:
    • Switch to copy mode in the sync settings
    • Copy mode doesn’t require admin rights
    • Trade-off: slower sync and more disk space usage
  3. Use the admin launcher:
    • Run runasadmin_main.py to automatically request elevation
See the Symlink mode guide for more details.
These errors occur when the mod manager cannot extract mod archives.

​
Error types

UnsupportedArchiveFormatError: Archive format is not supported
RarExtractionError: RAR extraction failed
ExtractionPasswordError: Archive is password protected

​
Solutions

For unsupported formats:
  • Manually extract the archive using 7-Zip or WinRAR
  • Place the extracted mod folder in the mods/ staging directory
For RAR files:
  • Ensure you have the necessary extraction tools installed
  • Try extracting manually if automated extraction fails
For password-protected archives:
  • Extract the archive manually using the provided password
  • Move the extracted mod to the staging directory
Supported archive formats typically include .zip, .7z, and .rar files. If extraction fails, manual extraction is always an option.
These errors indicate the mod file structure is incorrect or incomplete.

​
Error types

ModInvalidError: Mod is not a valid mod
ModFileNotFoundError: No .modfile found in [path]
MultipleModFoldersError: Multiple mod folders found in [path]

​
Common causes

  1. Missing .modfile:
    • Every valid mod must contain a .modfile file
    • This file contains metadata about the mod
  2. Multiple mods in one archive:
    • Some archives contain multiple mods
    • Extract and install each mod individually
  3. Incorrect folder structure:
    • The mod folder must contain the .modfile at the appropriate level

​
Solutions

For missing .modfile:
ModFileNotFoundError: No .modfile found in: [path]
  • Verify the mod is a valid BrownDustX mod
  • Check if the .modfile exists in a subfolder
  • Download the mod again from a trusted source
For multiple mods:
MultipleModFoldersError: Multiple mod folders found. Please install mods individually.
  • Extract the archive
  • Install each mod folder separately
  • Don’t try to install the parent folder containing multiple mods
Mods downloaded from unofficial sources may have incorrect file structures. Always download from trusted sources like the BrownDustX Discord server.
These errors occur when mod names conflict or contain invalid characters.

​
Error types

ModAlreadyExistsError: A mod named "[name]" already exists
InvalidModNameError: Invalid mod name "[name]". Check for illegal characters.
ModNotFoundError: Mod "[name]" was not found

​
Solutions

For duplicate mods:
  • Remove or rename the existing mod first
  • Check if you already have the same mod installed
For invalid names:
  • Avoid these characters in mod names: < > : " / \ | ? *
  • Use only alphanumeric characters, spaces, hyphens, and underscores
For missing mods:
  • Refresh the mod list
  • Verify the mod exists in the staging directory
  • Check if the mod was accidentally deleted
These errors occur when the mod staging directory has conflicts.

​
Error types

ModDirectoryNotEmptyError: Mod cannot be installed because a non-empty directory already exists
ModFileConflictError: A file exists at mods folder, which prevents the mod from being installed

​
Solutions

For non-empty directory:
  • A folder with the same name already exists in the staging directory
  • Remove or rename the existing folder
  • Then try installing the mod again
For file conflicts:
  • A file (not a folder) exists with the same name as the mod
  • Rename or remove the conflicting file
  • Retry the installation

​
Getting help

If you encounter an issue not covered in this guide:
  1. Check the logs:
    • Logs are saved to BD2ModManager-logs.log in the application data folder
    • Look for error messages and stack traces
  2. Run with debug logging: 
    BD2ModManager.exe --log-level debug
  3. Report the issue:
    • Open an issue on the GitHub repository
    • Include the error message and relevant log excerpts
    • Describe what you were doing when the error occurred
When reporting issues, never share the full log file publicly as it may contain sensitive information like file paths. Only share relevant error excerpts.

Build docs developers (and LLMs) love

Get started for freeTalk to us