Catch Broken Prefabs Before Merge: Automate Unity Asset Validation

Every Unity team has a war story: a prefab merges cleanly, passes review, and then explodes in the next scene load with a missing-script warning or a null reference in production. The asset pipeline is notoriously permissive. You can commit a prefab whose components are missing, whose material references are dangling, or whose scene hierarchy violates rules that only exist in your team’s shared memory. By the time someone runs the game and spots the problem, the broken prefab has already been copied into several scenes, overwritten by another branch, or baked into a daily build.

The fix is to catch broken prefabs before merge: automate Unity asset validation as a formal gate in your CI pipeline. In 2026, with Unity 6 and the maturity of Editor Automation, there is no excuse for leaving prefab validation to manual review. Using EditMode tests and a properly configured batch-mode CI step, you can write custom rules that inspect every prefab in the project and fail the pull request when something is wrong, before it ever reaches the main branch.

The Real Cost of Broken Prefabs at Review Time

Code review catches logic errors, not broken Unity assets. When a designer renames a component, deletes a nested GameObject, or reparents a prefab under a new root, the visual diff in a pull request is often opaque. The reviewer sees a few lines of YAML with GUIDs and m_Component references. Teams routinely skim past these files because they are unreadable and because the build will not fail until a scene is loaded at runtime.

The cost compounds quickly. A broken prefab that sits unnoticed for a week gets branched into feature work. Two developers fix it differently, creating a merge conflict on the prefab file itself. Conflict resolution then has a reasonable chance of resurrecting the original bug. Shifting validation left, into the editor test runner rather than the human reviewer, is the only scalable countermeasure.

Setting Up an EditMode Validation Test Suite

Unity’s EditMode tests run inside the editor process without entering Play mode. That makes them ideal for asset validation because you can load assets directly, inspect serialized properties, and abort the entire run if anything is malformed.

Start with a dedicated assembly definition for your tests. Create an Editor folder at Assets/Tests/Validation and add an asmdef that references UnityEngine.TestRunner and UnityEditor.TestRunner. Keep this assembly strictly inside an Editor folder so it never ships with the build.

Your first test file is a prefab audit that loads every prefab in the project and checks the most common failure mode: missing scripts.

using System.Linq;
using NUnit.Framework;
using UnityEditor;
using UnityEngine;

public class PrefabValidationTests
{
    [Test]
    public void Prefabs_Have_No_Missing_Scripts()
    {
        var paths = AssetDatabase.FindAssets("t:Prefab")
            .Select(AssetDatabase.GUIDToAssetPath)
            .Where(p => p.StartsWith("Assets/"))
            .ToArray();

        var failures = paths
            .SelectMany(path => PrefabsWithMissingReferences(path))
            .ToArray();

        Assert.IsEmpty(failures, string.Join("\n", failures));
    }

    private static string[] PrefabsWithMissingReferences(string path)
    {
        var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
        if (prefab == null)
            return new[] { "Unloadable prefab at " + path };

        var missing = prefab.GetComponentsInChildren<Component>(true)
            .Where(c => c == null)
            .Select(c => path);

        return missing.ToArray();
    }
}

This is the baseline. On a healthy project, it runs in under a second and guarantees that no prefab with a torn MonoBehaviour reference makes it to merge.

Writing Validation Rules That Match Your Pipeline

Generic rules catch generic problems. The real value comes from encoding your team’s specific conventions. Spend one sprint identifying the prefab mistakes that actually cost you debug time, then turn the top five into validation rules.

• Missing and broken references. Beyond missing scripts, check serialized fields that reference assets not found at load time. Use AssetDatabase.LoadMainAssetAtPath on each field’s path and verify that the GUID resolves to an existing asset.
• Scene hierarchy and layer rules. Many projects require all interactive objects to sit beneath a single root or to use a specific layer. A rule that enforces layer assignments is trivial and catches the classic “floor on the Ignore Raycast layer” bug.
• Prefab overrides and parent chains. Determine whether a prefab violates nesting rules. Some projects forbid nested prefabs beyond a certain depth, because prefab overrides can cascade silently and bloat the file size.
• Naming conventions. Asset names, component names, and tag names must match project standards. Rename blobs like Sphere (1) (2) (3) are a strong signal that objects were copied without cleanup.
• Animation events and callback hooks. Invalid method references on AnimationEvents, UnityEvents, or particle system callbacks are invisible to the compiler. A rule that walks serialized UnityEvent properties and compares target method names against the component type is a serious time-saver.

Here is an example rule that rejects prefabs with a collider on a child object whose scale is zero, a common prefab corruption that causes physics glitches without any visible editor error:

[Test]
public void Colliders_Do_Not_Sit_On_Zero_Scale_Objects()
{
    var offenders = new List<string>();
    foreach (var path in PrefabPaths())
    {
        var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
        foreach (var collider in prefab.GetComponentsInChildren<Collider>(true))
        {
            if (collider.transform.lossyScale.magnitude == 0f)
                offenders.Add(path + " :: " + collider.name);
        }
    }
    Assert.IsEmpty(offenders,
        "Zero-scale colliders found:\n" + string.Join("\n", offenders));
}

Keep each rule focused on one invariant. Overloaded tests fail loudly and give no signal about the actual fix.

Feeding Test Results Into CI and Failing the Pull Request

EditMode tests only matter if they run automatically. The canonical invocation runs the editor in batch mode with the test runner pointed at your validation assembly:

Unity -batchmode -projectPath . -runTests \
  -testPlatform EditMode \
  -testCategory "PrefabValidation" \
  -testResults results.xml \
  -quit

On GitHub Actions, this step runs in a self-hosted Unity runner or a container with a valid Unity license. The step fails when any EditMode test fails, and the resulting XML report maps back to the pull request checks.

The key detail is that the CI step must be a required check for the pull request, not just an informational job that runs in the background. If your branch protection rules let a PR merge with a failed status, the gate is theater. In most Unity CI pipelines today, the process is straightforward: fail the job on a nonzero exit code, and let the reporting integration mark the PR check as failed when assertions do not pass.

For teams using GitLab CI, the equivalent pattern is simple. The test step runs in the validate stage, the XML report is published as a test artifact, and the merge request cannot be accepted while the pipeline is red.

Rules Worth Stealing or Adapting for Your Team

Your first validation pass should be boring and effective. These five rules cover the majority of broken-prefab scenarios reported by teams working on mid-size multiplayer projects:

• Missing scripts on prefabs or their descendants
• Missing or broken asset references in serialized fields
• Prefabs that use unsupported layers or tags
• Duplicate MonoBehaviour IDs or broken m_Script GUID mappings
• Prefab imports that produced a warning in the console at import time

The last rule is especially useful. If an import warning is logged for a prefab, it is a signal that the asset is in a degraded state. Capturing console logs during the EditMode run and failing on LogType.Error or LogType.Warning for prefab assets will surface issues you did not even anticipate.

Common Pitfalls When Automating Asset Validation

Even a good validation suite has failure modes worth anticipating.

Tests that depend on the wrong platform. EditMode tests run against the active target platform. If a prefab contains a platform-specific component, a Windows runner can report a false failure for a Mac-specific import. Guard platform-specific checks with #if UNITY_EDITOR conditionals or restrict the test assembly to the platform you actually validate against.

Heavy AssetDatabase calls in loops. Loading every prefab via LoadAssetAtPath thousands of times is slow. Batch your loads and avoid calling FindAssets inside a per-prefab loop. Cache the path list once at the start of the run.

Stale asset caches in CI. Runner caches from previous jobs can hide stale prefab state. Force a clean asset import in CI at least once a day, or wipe the Library folder before the batch run when you suspect corruption.

Rules that mutate assets. A validation test must be read-only. If a test accidentally triggers a reimport or modifies a prefab, it will produce nondeterministic results and dirty the working tree. Use PrefabUtility.SavePrefabAsset only in dedicated migration scripts, never inside a validation test.

Conclusion

Broken prefabs are a class of bug that code review cannot reliably catch. By writing a small suite of EditMode validation rules and wiring them into your CI pipeline as a required pull request check, your team gets an automated guard that inspects every prefab on every merge, rejects malformed changes, and keeps the project’s assets honest. The rules are cheap to write, the runtime cost is measured in seconds, and the failures they prevent would otherwise surface as production bugs weeks later. Start with missing scripts, add the conventions your team lives by, and let the merge gate do the nagging.