Skip to main content
Deployment failures cluster. Almost all of them are one of six things, and most report something other than the actual cause. Work through these in order. The first three cover the large majority.

​
It works locally but not in production

The single most common report, and it is almost never mysterious. Local is not a smaller production. It is a machine with years of accumulated state that you cannot see and did not write down.
Antideploy detects every environment variable your code reads and separates what it can supply from what it must ask you for. That list is the fastest way to find the variable you forgot.

​
The site loads but every asset 404s

You deployed one file instead of the project. The page arrives, the build reported success, and the browser console is full of 404s for scripts, styles and images. This happens when an upload or an API push carries only the entry point. Check the file count. If you expected a project and see one file, the upload was wrong. Send the whole directory, not the file you think matters.

​
The build fails on install

The last one is worth checking first. A pinned engine range that no longer matches anything is a five second fix that looks like a toolchain problem.

​
The build succeeds and the app never starts

The container was built and then failed to come up. Three causes, in order of likelihood: It is not listening on the right port. The platform assigns a port at runtime and passes it in the environment. An app hardcoded to 3000 never receives traffic and is killed as unhealthy. Read the port from the environment with a fallback:
It is bound to localhost. Listening on 127.0.0.1 means nothing outside the container can reach it. Bind to 0.0.0.0. It crashed on startup. A missing variable, or a database query before the schema exists. The runtime logs say which.

​
The database exists but the tables do not

relation "users" does not exist, on the first request after a clean deploy. Your migration did not run, or ran after the app started. On Antideploy migrations run before the release, so a failed migration fails the deploy and leaves the previous version serving. If you are seeing this, the likely cause is that your migration tool was not detected. Check the detected spec.

​
It deployed fine and does not work

The most expensive category, because nothing reported an error.
  • Files written to local disk vanish. The filesystem is ephemeral. Uploads saved to disk survive until the next deploy and no longer.
  • In-memory state is not shared and does not survive. Sessions in memory, in-process caches, and rate limit counters reset on every restart.
  • Background workers and scheduled jobs do not start because you deployed a web service.
  • A webhook cannot reach you if you never told the sender the new URL.
These are the ones worth reading the hazards for. Antideploy reports them as structured data at analysis time, before the deploy, precisely because none of them will announce themselves afterwards.

​
Reading the failure rather than guessing

Every deploy records its steps, the analyzed spec, warnings and hazards, and the build log. Warnings are things that will work but probably are not what you meant. Hazards are facts about what will not work once live. Both come back as structured data rather than a red box, which means a coding agent can read them and act on them without a human relaying the message.

See what your project would hit

The analysis runs before anything is built, so you can read the warnings without deploying.