MonoGame ContentLoadException and platform-specific path resolution

Direct Answer

MonoGame does not include a built-in MGCB setting or build-time validator that enforces case-sensitivity between Content.Load string arguments and the compiled .xnb filenames on disk. The recommended strategy is to adopt a strict naming convention—such as lower_case_with_underscores—for every asset and every code reference, and to verify the casing manually before packaging for a case-sensitive target.

Platform Path Resolution Explained

The ContentManager resolves asset paths relative to the configured Content root directory. Once that path reaches the operating system’s file layer, behavior diverges by platform:

• Windows (NTFS/FAT32) is generally case-insensitive, so Content.Load("Asset") succeeds even if the file is named asset.xnb.
• Android (ext4/f2fs) and Linux file systems are case-sensitive, so the same call throws a ContentLoadException unless the casing matches exactly.

Confirmed Behavior vs. Probable Cause

Confirmed: The MGCB Editor compiles source assets into .xnb files without validating whether the string passed to Content.Load matches the output filename casing. Windows masks the mismatch; Android and Linux expose it.

Likely explanation: Your deployment is hitting a case-sensitive file system, and at least one Content.Load literal differs in casing from the physical .xnb name. This is the most common trigger for a runtime ContentLoadException when assets are known to exist in the build output.

Steps to Fix and Prevent Recurrence

1. Standardize naming. Rename all content assets and their corresponding Content.Load calls to a single convention, e.g., player_ship.xnb and Content.Load<Texture2D>("player_ship").
2. Audit string literals. Renaming a file inside the MGCB Editor does not update C# source strings. Search your codebase for Content.Load and compare each argument to the actual .xnb filename.
3. Inspect the deployment package. Before installing on a device, list the archive contents to confirm casing. For an APK, a read-only inspection is sufficient.
4. Test early on a case-sensitive host. Run the game on Linux or Android during development rather than waiting for final QA.

Safe Verification Commands

These commands are read-only and scoped to asset inspection:

# List .xnb files in the build output (Linux/macOS terminal)
find ./bin -name "*.xnb"

# Inspect APK contents without extracting (requires unzip or similar)
unzip -l app.apk | grep -i "assets/.*\.xnb"

Assumptions and Uncertainty

This guidance assumes the default ContentManager root behavior and standard platform file systems. If you use a custom root directory, a virtual file system, or a third-party content resolver, the root mapping may differ, but the underlying case-sensitivity rule remains. Exact MGCB validation behavior can vary by MonoGame version; the absence of a casing validator is the long-standing, widely observed behavior across 3.x releases.