When an AI Coding Agent Cannot Run Your Build
An agent that cannot compile your project does not stop. It keeps editing, reasoning about code it has never seen run, and the result is a confident diff nobody has tested.
The failure is quiet. An AI coding agent cannot run your build, so it falls back to the only thing it can still do, which is read code and edit it. Twenty minutes later you have a forty-file diff that compiles in nobody's imagination but the model's. The tests were never run. The type errors were never seen. The agent will tell you the change is complete, and from inside its context that is a reasonable thing to believe.
What makes this worse than an obvious error is that the output looks normal. A diff is a diff. The missing information is that no part of it was ever executed.
Why a broken build is worse than a slow agent
An agent working on code has two feedback sources: reading the code, and running it. Take away the second and you have removed the only one that can contradict the first. Every assumption it makes about an import path, a function signature or a config key goes unchecked, and the errors compound because each edit is reasoned from the previous unverified edit.
This is the same mechanism behind an agent whose fix fails in CI, one step earlier. In the CI case the agent ran something locally and CI disagreed. Here it ran nothing.
The four reasons an AI coding agent cannot run your build
Ask the agent for the exact command it ran and the first twenty lines of output. That one request usually identifies the cause.
One: the toolchain version is wrong or missing
Symptoms: command not found, a syntax error in your own config file, a package manager refusing a lockfile version, an engine mismatch warning followed by failure.
Your machine has the right Node, Python, Go or JDK because you installed it eighteen months ago and forgot. A fresh environment does not. Lockfiles pin dependencies, not the runtime that reads them.
Fix: pin the runtime in the repository where a tool will find it. A version file, an engines field, a toolchain declaration, whichever your ecosystem uses. Then verify it is actually honoured, because a version file that nothing reads is decoration.
Two: the network blocks the package registry
Symptoms: npm install or pip install hanging then timing out, TLS errors, a private registry returning 403, downloads of exactly zero bytes.
This is the cause people diagnose last and it is increasingly the most common, because agent sandboxes restrict egress on purpose. Claude Code's sandboxing documentation is explicit that sandboxed commands have "no direct route out" and that connections go through a proxy checking each host against allowed domains, which "start empty". An empty allow list means a clean install cannot work until you add your registry.
Fix: add your package registry and any internal hosts to the allowed-domain list, and nothing else. If you use a private registry with a token, see cause three, because the token is usually missing too.
Three: environment variables are absent
Symptoms: the build starts and dies reading config, undefined is not a function on a config object, a database connection refused at build time, a private registry 401.
Your .env is correctly gitignored, so the agent has a repository with a hole in it. Builds that read secrets at build time fail immediately and the error rarely says "missing environment variable", it says whatever the library says when a value is empty.
Fix: commit an .env.example with every key present and every value fake, and make the build fail loudly with a named key when something required is missing. A build that announces DATABASE_URL is not set is self-diagnosing. Keep the real values out of the repository entirely, per our note on where secrets should actually live.
Four: platform-specific binaries
Symptoms: a module that will not load with an architecture error, an installed package failing at runtime, image or crypto libraries complaining, something that works on your Mac and not in a Linux container.
Lockfiles record package versions, not compiled artefacts. Native modules build against the host, and an agent in a Linux container is not your laptop.
Fix: install rather than copy node_modules or virtual environments, and make sure your lockfile includes the platform entries for the target. Where a project genuinely depends on the host, the answer is to standardise the host.
The instruction that prevents the bad diff
Whatever the cause, the behaviour to change is the agent continuing. Put this in your repository instructions, where the agent reads it at the start of every session rather than in a one-off prompt:
Before changing code, run the build and the test suite once and report the result.
If the build or the tests cannot run at all, stop. Do not edit source files.
Report: the exact command, the first 20 lines of output, and which of these
you think it is: missing toolchain, blocked network, missing env var,
platform mismatch.
Never modify build config, lockfiles, CI config or dependency versions to
make a build succeed unless I ask you to fix the build specifically.The last clause matters more than the rest. An agent told to make the build pass will reach for the build config, and a diff that quietly loosens a compiler option or downgrades a dependency to resolve a conflict is a much more expensive problem than a build that failed honestly. It is the same pattern as an agent changing tests to make them pass, applied to the toolchain.
Fix it once, with a defined environment
The durable answer is to stop relying on the agent to reconstruct your environment. A dev container declares the toolchain, the setup command and the environment variables in a file the agent reads, which removes causes one, three and four in one move. The Development Containers specification defines the properties that do it: image for the base, features for toolchains, postCreateCommand for the install step and containerEnv for variables.
Two habits complete it. Make build and test single commands with no undocumented prerequisites, because an agent will run npm test and will not infer that a local service must be started first. And in a large repository, scope the agent to a buildable unit rather than the whole tree, so one package failing to install does not block work in another.
Then verify, rather than trust. The claim "I ran the tests" is checkable, and checking whether your agent actually ran them is a short exercise that catches this failure mode at the point where it is still cheap. For picking tools that handle environment setup well in the first place, see our guide to choosing AI coding tools.
Ask for evidence, not a claim
Even with the stop-and-report instruction, you want proof rather than an assertion. Two mechanisms are cheap.
Ask for the build output in the handover rather than a summary of it. "Paste the last ten lines of the test run" is checkable in a second, and an agent that cannot produce them has answered the question without any argument about it.
And make the absence of a build visible in review. The pattern to catch is a diff that touches source files with no accompanying evidence of execution: no lockfile change, no snapshot update, no test file touched, and a confident description of runtime behaviour. That combination means the behaviour was reasoned about rather than observed.
Each of the four causes above leaves a trace in the first lines of output, so a reported failure is nearly always diagnosable from the agent's own transcript. What is not diagnosable is a clean-looking diff from a session where the build never ran, because there is nothing to read.
Frequently asked questions
Why does the agent keep editing code when the build is broken?
Because nothing told it to stop, and editing is the task it was given. Reading code still works, so from inside its context it is making progress.
How do I tell a network problem from a missing dependency?
Look at the first failing line rather than the summary. Timeouts, TLS errors and 403s are network. Resolution errors and version conflicts are dependencies.
Should I give the agent my .env file?
No. Give it an example file with every key and fake values, and make missing required keys produce a named error. Real secrets in an agent's context end up in logs.
Is it safe to let the agent fix the build itself?
Only when fixing the build is the task you asked for, and only with a diff review focused on build config, lockfiles and dependency versions. Those are the files where a silent loosening hides.
Does running the agent in CI avoid this?
It moves the problem. CI has a defined environment, which helps, but it usually has narrower network access and fewer secrets, so causes two and three show up there instead.
How did this land?
About the author

Staff Engineer, Platform
Carlo works on the platform that turns prompts into running apps. He writes the engineering deep dives and the changelog notes worth reading.


