Fix Unity ScriptableObject Singleton Null After Build

This bug always shows up at the worst time: the build looked fine until you launched it and saw a cascade of NullReferenceException errors on your game’s config object. The ScriptableObject is there in your project, it works in Play mode, and it still returns null the moment you hit F5 on the standalone player. The problem is how the asset gets into the build, not how it loads.

Understand what Unity ships

When Unity packages a build it walks the dependency graph starting from scenes listed in Build Settings. Any prefab, material, texture, or ScriptableObject reachable through that graph is included. Anything else is stripped. This is intentional — it keeps your build small — but it catches out anyone who loads assets by path only.

There are four ways to make a ScriptableObject asset survive the strip:

• Reference it directly from a field on a MonoBehaviour in a built scene.
• Place it inside any folder named Resources and load with Resources.Load.
• Mark it Addressable and load via the Addressables API.
• Pack it into a classic AssetBundle and load that bundle at runtime.

The direct reference pattern

The cleanest approach for a singleton is a bootstrap MonoBehaviour in your first scene that holds a serialized reference to the asset and publishes it through a static field:

public class GameConfigBootstrap : MonoBehaviour {
    [SerializeField] private GameConfig config;

    void Awake() {
        GameConfig.Instance = config;
        DontDestroyOnLoad(this.gameObject);
    }
}

Because the field is serialized and the GameObject lives in a built scene, Unity includes the asset automatically. You do not need Resources and you cannot forget to register it.

When Resources is acceptable

For small, always-loaded config that you genuinely want available before any scene loads, Resources is fine. Move the asset into a folder literally named Resources anywhere in Assets/, drop the extension from the load call, and be aware that every file under those folders ships regardless of references:

public static GameConfig Instance => _instance ??= Resources.Load<GameConfig>("GameConfig");

If Resources.Load returns null in a build, the most common causes are a misspelled path, the file not actually being in a Resources folder, or an extension accidentally included in the string.

Addressables gotchas

Addressables solve the same problem with async loading and remote content, but they introduce their own failure modes. An entry must be present in the Addressables settings at build time; the content catalog must be built alongside the player. If you enable “Use Asset Database” for local runs and forget to swap to “Use Existing Build” before the player build, the catalog will be missing. Always build content with “Build -> New Build -> Default Build Script” before the player build on CI.

Never rely on AssetDatabase at runtime

AssetDatabase and anything under UnityEditor is stripped from builds. If your singleton’s lazy getter calls AssetDatabase.LoadAssetAtPath, it will compile only because the call is inside an #if UNITY_EDITOR block or behind a platform check — and the block returns null on the player path. Search your codebase:

# Quick audit
grep -rn "AssetDatabase.Load" Assets/Scripts/

Every hit needs a runtime equivalent, not a silent fallback.

“If the asset does not appear in the Build Report, it is not in the build. Stop debugging your loader and start debugging your references.”

Related Issues

For similar editor-versus-build discrepancies, see Fix Unity prefab variant overrides being lost. For singleton lifecycle in another engine, Fix Godot autoload singleton not accessible covers the same failure mode.

Tip: open the Build Report window after every build — if your singleton is missing there, you already know where to look.