Editor Works, Build Fails: Trace Console Errors to Script and Scene Refs with Unity MCP

Threads titled “Unity works in editor, fails on device / build” look the same: Play is fine, then a Player / device build goes red, crashes, blacks out, or throws NullReferenceException on scene enter. The engine is rarely “broken”—the editor path hid reference and platform gaps: scene not in the build list, serialized fields that are None on disk, path case sensitivity, or UnityEditor APIs leaked into a runtime assembly until pack time.

This post has three spines (same as the title):

1. Console / stack → script and scene objects
2. Verify Build Settings, Missing Script, serialized refs
3. Read-only diagnose in Cursor via Unity MCP → minimal fix after you confirm

No plugin install walkthrough, no full store shipping guide. IL2CPP stripping and native plugins stay in the appendix.

Related:

• Unity MCP install
• Unity MCP with Claude Code and Cursor
• Wire an AI Studio HUD to health events (correct wiring; this post is “how to find the break”)

First: which layer failed?

A. Build window red (compile / pack failure)
        ↓
B. Build succeeds; device dies or blacks out on launch
        ↓
C. Game starts; a scene or feature blows up at runtime

What you see	Layer	Check first here
Build fails, error CS… / type not found	A	Runtime assembly referencing UnityEditor, bad #if, asmdef
NRE / MissingReference on boot scene	B/C	Scene in build list, Missing Script, None in Inspector
Only fails on Resources.Load / additive scene	C	Path case, asset in pack, scene actually loaded

Unity MCP is strongest on an open editor: Console, Hierarchy, component fields. Device logcat / Xcode stacks must be pasted into Cursor—or ship a Development Build and reproduce with the same boot scene in Editor when you can.

Troubleshooting loop (manual + MCP)

Do not skip the manual pass and ask AI to rewrite Player.

Step 0: Freeze the scene by hand (~2 min)

Before Cursor:

1. Note Unity version and target (e.g. Android / IL2CPP)
2. Clear Window → General → Console, then Build or Development Build once
3. Copy the first relevant Error (with stack)—not a Warning wall
4. Open File → Build Settings: is the suspect scene checked? Is index 0 the boot scene?
5. If you edited a Prefab instance: did you Apply? Unapplied overrides often never hit the disk asset you think you shipped

Step 1: MCP read-only Console triage

Summarize Console Errors related to this build / last Play (ignore Info).
Classify as compile / Missing Script / NullReference / resource load.
List script path, line, GameObject name per error when present.
Do not modify any assets.

Step 2: Manual + MCP “reference trio”

For runtime NREs (B/C), select the stack object in the editor and cross-check with MCP:

Manual	MCP prompt
Build Settings list (screenshot or dictation)	“List Build Settings scene paths and enabled flags; name the boot scene.”
Inspector: Missing Script / None refs	“In scene <Name>, list Missing Scripts; check serialized fields on <Object>.<Component> for None. Table only. Do not edit.”
Prefab asset vs scene instance	“Is <X> a Prefab asset or scene instance? Any unapplied overrides if visible? Report only.”

Rule: Packs use on-disk scenes/Prefabs. Temporary OnValidate fills that “look fine” in Editor do not count—trust serialized values from MCP/Inspector.

Step 3: Diagnose template, then confirm

[Constraints]
- Diagnose and propose a minimal plan; wait for my OK before editing
- Do not fake a fix with mass GameObject.Find
- Touch only scripts/Prefabs/scenes tied to this Error

[Scene]
- Editor Play: OK / broken (truthful)
- Platform / build: …
- Build Settings boot scene: …
- Console / device stack (raw):
<paste>

[Answer]
1. Layer A / B / C
2. Top 1–2 root causes (not in build / None ref / Missing Script / case / Editor API…)
3. Objects and field names I should verify
4. Minimal fix steps (still do not execute)

Step 4: Minimal write + recheck

Apply the confirmed minimal fix: only <object.field> or the few lines in <script path> for this Error.
Save scene/Prefab.
Then read-only recheck: fields still None? Same Error still in Console?

Worked example: stack → field

Synthetic but realistic Player/device log (swap paths for your project).

Log

NullReferenceException: Object reference not set to an instance of an object
  at HudHealthView.HandleHealthChanged (System.Single current, System.Single max) [0x00000] in Assets/Scripts/UI/HudHealthView.cs:42
  at PlayerHealth.TakeDamage (System.Single amount) [0x00000] in Assets/Scripts/Combat/PlayerHealth.cs:28
  at DebugDealDamage.Update () [0x00000] in Assets/Scripts/Debug/DebugDealDamage.cs:15

Layer

• Reached Update → not A (compile OK)
• Dies on damage → C (runtime); suspect UI refs, not “rewrite combat”

Manual

1. Is the HUD’s scene in Build Settings?
2. Select the HudHealthView object; are healthFill / playerHealth None?
3. Prefab edits: Applied?

MCP

Read-only: open the scene that contains the HUD.
1. Find objects with HudHealthView
2. Report whether healthFill, playerHealth (and peers) are None / Missing
3. Do not edit
If None: minimal plan is reassign refs and save—not change TakeDamage.

Minimal fix (after OK)

• Drag HUD_HealthFill Image → healthFill; Player’s PlayerHealth → playerHealth
• Save; Development Build; take damage again

Bad “fix” (do not)

// Anti-pattern: Find hides None — still breaks on rename / additive load
healthFill = GameObject.Find("HUD_HealthFill").GetComponent<Image>();

Correct wiring: HUD → health events. Here: pin the field from the stack, then rebind.

Symptom matrix (spine)

Symptom 1: Build red — type not found / UnityEditor

Likely cause	Manual	MCP
Runtime script uses Editor API	Is the file outside Editor/?	“Search UnityEditor. outside Editor folders; list paths only.”
Inverted #if, Player missing types	Check UNITY_EDITOR wraps	“Which types exist under Editor vs Player for this file?”
asmdef gap	Open the failing .asmdef	“List asmdef refs; which one is missing?”

Anti-pattern (Editor API in a runtime assembly → Player build fails):

using UnityEngine;
using UnityEditor; // Fails build if not an Editor assembly

public class BadBake : MonoBehaviour
{
    [MenuItem("Tools/Bad")] // further UnityEditor dependency
    static void Run() { }
}

Fix A: whole file under Editor/

Assets/Scripts/Editor/BakeTools.cs   ← editor-only compile

Fix B: isolate in-file (only if you must share a file)

using UnityEngine;

public class RuntimeSafe : MonoBehaviour
{
    public void DoGameplay() { /* visible to Player */ }

#if UNITY_EDITOR
    [ContextMenu("Debug/Fill Refs")]
    void EditorOnlyFill()
    {
        // Editor only — do not treat this as packed runtime data from Awake
    }
#endif
}

Cleaner still: Editor-only scripts + asmdef so runtime assemblies never drag Editor refs.

Symptom 2: Device NRE on scene enter; Editor Play “seems fine”

Check in order—no parallel mega-rewrite:

1. Scene not in Build Settings or wrong boot scene
2. Missing Script / serialized None (including unapplied Prefab)
3. Additive scene not loaded before Find / access
4. Resources.Load path case (macOS Editor often case-insensitive; Android is not)

1. Report Build Settings scenes, enabled flags, boot index
2. List all Missing Scripts in scene <X>
3. Check public refs on GameManager / Player / HUD along the boot path for None
Report only; do not edit.

In Editor	In pack	Typical cause
Refs look set	Runtime None	Unapplied instance overrides; wrong scene file edited
Find works	Device null	Object in unloaded scene; name mismatch
Resources.Load works	Device null	Path case; asset not under Resources/

// On disk: Assets/Resources/UI/HealthBar.png
// Often fails on Android (case mismatch):
Resources.Load<Sprite>("ui/healthbar");
// Match the path under Resources, e.g.:
Resources.Load<Sprite>("UI/HealthBar");

Search Resources.Load / Addressables.LoadAssetAsync path strings;
build a case-sensitive table vs real relative paths. Do not edit code yet.

Symptom 3: Console flooded with Missing Script

Scan scene <X> and Prefab <path>:
List GameObject paths with Missing Script.
Per item: suggest reattach original script or remove empty component (from leftover name/GUID if visible).
Do not bulk-delete automatically.

Manual: confirm the script file still exists and asmdef/GUID did not break; confirm one-by-one before deleting empties.

Acceptance checklist

1. Matching Errors gone from Console
2. Editor Play walks the same failing path (enter level, take damage, open UI…)
3. One Development Build to the target (or local Player)
4. MCP read-only recheck: suspect fields no longer None / Missing
5. Git diff is only the expected small scene/Prefab/script change—no drive-by refactor

Read-only recheck: any None or Missing Script on <object list>? List exceptions. Do not edit.

Prompt red lines

Do not	Do
“Just make Play work”	Layer A/B/C + pin the field from the stack
Mass Find instead of refs	Fix serialized fields or explicit injection
Reorder Build Settings unasked	Report current list and boot scene first
“There’s an NRE”	Paste the first 20–40 stack lines

Product boundaries

• Unity MCP: editor Console, Hierarchy, scripts, refs—this article’s spine.
• AI Studio: UI structure into the engine; rebind after re-export per the wiring post—do not Find UI from gameplay.
• Certificates, stores, OEM ROMs: paste log text into Cursor for reading help; out of MCP scene-edit scope.

Appendix: common but off-spine

Rule out this article’s spine first:

Symptom	Direction
Development OK, Release dies	Managed Stripping / link.xml; MCP: “Guess stripped types from crash stack; propose link.xml; do not write files yet.”
Android native crash (unmanaged)	.so / permissions / Gradle; paste logcat for reading
Unity API off main thread	Check async callbacks return to main thread

Do not merge stripping and Missing Script into one “big rewrite.”

Summary

1. Editor OK / pack broken → treat as refs / scenes in build / paths / Editor API first
2. Manual freeze of Build Settings + first Error, then MCP read-only triage
3. Stack → script line → component field; rebind or remove empty components after confirm
4. No Find or gameplay rewrites as fake fixes
5. Accept with Development Build + read-only recheck

Run “freeze → layer → reference trio → pin field like the sample” and most device ref bugs shrink to a reviewable small diff.