A build input the toolchain declines to ingest fails at every reference to its contents, not at the input itself

The lesson

Build toolchains that consume directories rather than individual files have to decide which directories are theirs. That decision runs before any real work, and the common implementation is a filter: recognised names are ingested, everything else is passed over. A name the filter does not accept is skipped, not rejected. No diagnostic is emitted, because from the tool's perspective nothing is wrong — there is simply less input than there was.

The consequence is that the error is displaced. Everything the skipped directory contained is now undefined, so the build fails at every reference to those contents: an import, a manifest entry, a symbol lookup. Those reference sites are usually stable files that the change never touched. The error message names one of them, points at a line that has been correct for a long time, and says nothing about the directory that was actually edited.

Two things then push the investigation the wrong way. First, error locality is normally a reliable heuristic — the named file is usually where the problem is — and here it is exactly inverted. Second, the symptom follows a rename, which is the classic shape of a stale build cache, so the cheapest-sounding theory is to clean and rebuild. That theory is wrong, takes a full build to disprove, and leaves the actual cause untouched.

There is an upstream cause worth separating from the mechanism. A linter's suggestion is a hypothesis about equivalence, not a verified refactor. A static analyser reasons about one property in isolation and reports that a distinction is redundant. It is usually right about that property and it does not check the second-order question of whether the resulting name is one the rest of the toolchain will still accept. Low severity describes the problem the tool found; it says nothing about the risk of the fix. The cheapest possible defence is to rebuild after acting on any of them, including the ones that look purely cosmetic.

The failure that taught it

A greenfield mobile application was building cleanly. A routine static-analysis pass over it raised only low-severity findings, one of which observed that a platform-version qualifier on an asset directory was redundant, because the project's minimum supported version already exceeded the version in the qualifier. That observation was correct. The suggested fix was to drop the qualifier from the directory name.

After the rename the build failed, reporting that a named asset could not be found and pointing at the application's manifest — a file that had not been edited in that change, on a line referencing the asset in the ordinary way. The files themselves were still present on disk, correctly named, inside the renamed directory.

Because a rename had immediately preceded the failure, the first theory was an incremental-build cache still tracking the old directory name. A clean build disproved it in about a minute and produced exactly the same error.

The observation that settled it cost one command and should have come first: listing the toolchain's merged intermediate output showed entries for the other asset directories and no entry whatsoever for the renamed one. That is negative evidence and unambiguous — the directory had never been read. The tool had emitted no complaint about a directory it declined to ingest, and the only visible trace was an absence in an intermediate folder nobody normally looks at.

The precise reason that particular name was not accepted was never isolated, and it did not need to be. Restoring the original qualifier restored the build. The static-analysis warning it reinstates is cosmetic, and the working build is worth more than clearing it.

How to apply it

• Rebuild after acting on any linter suggestion, cosmetic ones included. The severity of a finding describes the problem it found, not the risk of the change it proposes. Batching a dozen style-only fixes and committing without a build is how one of them hides.
• When a build reports something missing that is present on disk, inspect the toolchain's intermediate output before theorising about caches. Whether the artifact appears there is a single cheap question that splits two investigations costing very different amounts: present means a resolution problem, absent means the input was never read. Do this first, not after a clean build has already been spent.
• Treat a missing-input error as pointing at the producer, not the consumer. The file named in the message is where the reference lives. When a change has just moved or renamed something, suspect the thing that moved, however unrelated the named file looks.
• Distrust error locality specifically after a rename. It is a good heuristic in almost every other situation, which is what makes it costly here.
• Prefer the layout the toolchain's own scaffolding generates. Directory names that a project template produces are the ones the toolchain is exercised against; a name derived by reasoning about what ought to be equivalent has no such guarantee behind it.
• When the cause of a rejection cannot be isolated cheaply, reverting to the working shape is a legitimate end state. Record what was observed rather than inventing a mechanism to explain it; a lesson that overstates its own certainty is worse than one that names the boundary of what was seen.