---
title: "Pitfalls: import pipelines & evidence"
slug: /workflows/pitfalls-data/
markdown: /workflows/pitfalls-data.md
section: pitfalls
tier: 2
summary: "Absence needs two sources; gates that cannot fail."
sources: ['pitfalls/data.md']
canonical: https://unityworkflowlibrary.dev/workflows/pitfalls-data/
read_first: /read-first.md
---

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

# Pitfalls: import pipelines & evidence

> Absence needs two sources; gates that cannot fail.

Generalized pitfalls from asset-import and extraction pipelines in 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).

- **A-NEGATIVE-NEEDS-TWO-SOURCES — before declaring content absent, confirm with two independent sources.** Check: absence claims cite a full-index search and a second method. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (A-NEGATIVE-NEEDS-TWO-SOURCES): "no water in the data" was repeated for days; the data had it, the scoped census and a failing parser did not.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **PARSE-FAILURE-LOOKS-LIKE-ABSENCE — assume a parser failed before concluding data is missing.** Check: assert parsed counts against the source's own declared counts; make deserialization failures fatal. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (PARSE-FAILURE-LOOKS-LIKE-ABSENCE): A line-based manifest parser resolved 0 records after the file was pretty-printed; a deserializer swallowed errors by default.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **A-GATE-THAT-CANNOT-FAIL-IS-NOT-A-GATE — checks like "properties > 0" pass on partial/broken output.** Check: gates compare against an independent oracle (expected count, known values). Status: locked (empirical, seen in shipped/active projects).
- **PER-ITEM-GUARDS-HIDE-SYSTEMIC-FAILURE — a try/catch per item turns "everything failed" into silence.** Check: count per-item failures and fail the batch above a threshold. Status: locked (empirical, seen in shipped/active projects).
- **FIX-PASSES-MUST-UNDO-THEIR-OWN-OUTPUT — an additive binder can never remove a wrong bind it made earlier.** Check: fix passes recompute from source and clear prior generated output. Status: locked (empirical, seen in shipped/active projects).
- **RESUMABLE-JOBS-WRITE-PROGRESS-FIRST — write the progress marker atomically with (or before) the records it covers.** Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (RESUMABLE-JOBS-WRITE-PROGRESS-FIRST): A killed job re-walked and duplicated records.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **ZERO-TRANSFORMS-ARE-PADDING — a location of exactly (0,0,0) in imported placement data is a defaulted value, not a placement.** Check: sweep the whole manifest for zero transforms and refuse them at import. Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (ZERO-TRANSFORMS-ARE-PADDING): Geometry rendered floating at the world origin.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **A-MISSING-MAP-STILL-RENDERS — dropped normal/roughness maps fail silently; the tell is a ratio (textures exported vs bound).** Check: report bound/available ratios per map type after import. Status: locked (empirical, seen in shipped/active projects).
- **VERIFY-TEXTURE-PACKING-FROM-PIXELS — channel packing must be verified from pixel statistics, never from suffixes or parameter names.** Check: channel-correlation test (real albedo is strongly correlated RGB). Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (VERIFY-TEXTURE-PACKING-FROM-PIXELS): Masks bound as albedo, emissive alpha mistaken for opacity.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **FLAT-NORMALS-ARE-WORSE-THAN-NONE — binding an identity/flat normal makes a material report "has normal" while adding nothing.** Check: exclude placeholder normals from coverage metrics. Status: locked (empirical, seen in shipped/active projects).
- **EMISSIVE-MAPS-NEED-AN-EMISSIVE-COLOR — a bound emissive map multiplied by a default black emissive color emits nothing.** Check: set emissive color/intensity when binding emissive maps. Status: locked (empirical, seen in shipped/active projects).
- **BAKED-BOUNDS-OFFSET-VS-PIVOT — analyse imported meshes at their bounds centre but instantiate at the pivot.** Status: locked (empirical, seen in shipped/active projects).

> **Why this rule exists** (BAKED-BOUNDS-OFFSET-VS-PIVOT): Half the meshes landed offset by their baked bounds.
> *Source: Pitfall log of a shipped or active Unity project, generalized.*

- **ORIENTATION-IS-MEASURED-NOT-EYEBALLED — a wrong axis mapping can still score high visual overlap.** Check: verify coordinate conversion with asymmetric reference points. Status: locked (empirical, seen in shipped/active projects).
- **CRLF-POISONS-PATH-LISTS — lists written on Windows carry a trailing carriage return that makes every lookup miss.** Check: strip line endings when reading path lists. See also PERL-MULTILINE-MISSES-CRLF. Status: locked (empirical, seen in shipped/active projects).
- **DEV-PLACEHOLDERS-SHIP — retail content contains test/placeholder assets.** Check: filter by explicit placeholder paths/materials during import. Status: locked (empirical, seen in shipped/active projects).