---
title: "Pitfalls: builds, editor automation & profiling"
slug: /workflows/pitfalls-build/
markdown: /workflows/pitfalls-build.md
section: pitfalls
tier: 2
summary: "Batchmode skips, unfocused editors, rolling profiler buffers."
sources: ['pitfalls/build.md']
canonical: https://unityworkflowlibrary.dev/workflows/pitfalls-build/
read_first: /read-first.md
---

> Read first, on every prompt: [non-destructive rules](/read-first.md).

# Pitfalls: builds, editor automation & profiling

> Batchmode skips, unfocused editors, rolling profiler buffers.

Generalized pitfalls from shipped and active projects. Record your own project's traps the same way: [Keeping a project pitfall file](/workflows/pitfall-file/). All entries LOCKED evidence. Status: locked (empirical, seen in shipped/active projects).

- **EXECUTEMETHOD-NEEDS-A-CLEAN-COMPILE — batchmode `-executeMethod` silently does not run when any package fails to compile.** Check: read the log for compile errors and assert the method's own log line. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (EXECUTEMETHOD-NEEDS-A-CLEAN-COMPILE): Build scripts "succeeded" without building; an IDE integration package also crashed batchmode.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **UNFOCUSED-EDITOR-DOES-NOT-TICK — an unfocused Editor in Play Mode may not advance frames (`Time.frameCount` stays put), and script compilation requests just queue.** Check: enable "run in background"/focus the Editor for automated runs; wait on a confirmed compile event. Status: locked (empirical, seen in shipped/active projects).
- **PROFILER-BUFFER-ROLLS — the Profiler keeps only a rolling window (~2000 frames); pausing Play does not pause recording, so idle editor frames evict the gameplay frames.** Check: stop recording (not just Play) before reading; save captures. Status: locked (empirical, seen in shipped/active projects).
- **EDITORLOOP-IS-NOT-THE-GAME — in the Editor, EditorLoop self-time dominates frames; judge game cost by PlayerLoop, not total FPS.** Check: perf claims cite PlayerLoop or a player build. Status: locked (empirical, seen in shipped/active projects).
- **SPACES-IN-PATHS-BREAK-SHELL-SWEEPS — `$(find ...)` word-splits folder names with spaces and checks nothing.** Check: use null-delimited lists and assert a non-zero file count. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (SPACES-IN-PATHS-BREAK-SHELL-SWEEPS): A mechanical check passed because it scanned zero files.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **RELEASE-PIPELINES-PRUNE-THEIR-OUTPUT — repeated platform exports and archives fill the build host disk.** Check: the ship path deletes old exports/archives beyond N. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (RELEASE-PIPELINES-PRUNE-THEIR-OUTPUT): IOS export folders, archives and packages filled a build machine.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **DEVELOPMENT-PLAYERS-ARE-NOT-FOR-SHARING — a Development build carries debug symbols per assembly and a profiler listener with the build PC's address.** Check: shared/test builds are non-Development unless profiling is the goal. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (DEVELOPMENT-PLAYERS-ARE-NOT-FOR-SHARING): Patches several times larger than the change, and builds shared with testers advertised the developer's LAN address.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **CHECK-AND-ACTION-ARE-SEPARATE-COMMANDS — a guard ("is a compile running?") and the action it guards must not be one chained command.** Check: read the guard result, then send the action. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (CHECK-AND-ACTION-ARE-SEPARATE-COMMANDS): The guard printed "busy" after the action on the next line had already started.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **PIPELINE-EXIT-CODES-COME-FROM-THE-LAST-STAGE — `tool | tail` reports tail's status.** Check: `set -o pipefail` or check the first stage's status. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (PIPELINE-EXIT-CODES-COME-FROM-THE-LAST-STAGE): A repository integrity check piped through `tail` read as clean while the check had failed.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **GREP-JSON-KEYS-NOT-WORDS — grepping a JSON status for "failed" matches `"failed":false`.** Check: parse JSON for status checks. Status: locked (empirical, seen in shipped/active projects).
- **SERIALIZEDPROPERTY-NEXT-TRUE-WALKS-EVERYTHING — iterating `SerializedObject` with `Next(true)` over large assets enters every array element and can hold the main thread for minutes.** Check: use `NextVisible(false)` or target properties by path. Status: locked (empirical, seen in shipped/active projects).