Build failures
When npm, composer or pip fail during the build, and the images we refuse.
The build log on the deploy page shows the exact error, usually near the end. The usual causes:
A dependency doesn't install
What you see
npm ERR!, ERESOLVE, Your requirements could not be resolved, No matching distribution found.
Why
A lockfile out of date, a package that needs another version of Node, PHP or Python, or a private package.
Fix
Run the same install locally from a clean folder (npm ci, composer install, pip install -r requirements.txt) and commit the lockfile it produces.
Pin your runtime version: .nvmrc or engines for Node, .python-version for Python, require.php in composer.json.
The build command fails
What you see
TypeScript errors, next build or vite build failing, a missing environment variable at build time.
Why
The code doesn't build in a clean environment, or it needs a variable during the build.
Fix
Run npm run build locally from a fresh clone. Add build-time variables (NEXT_PUBLIC_*, VITE_*) in Variables before deploying.
Node says ERR_REQUIRE_ESM
What you see
Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported.
Why
A CommonJS app requires an ESM-only package (uuid 11+, nanoid 4+, chalk 5…).
Fix
We already turn on Node's require(esm) support on Node 22. If you pinned an older Node, move to Node 22, or use import() for that package.
“This image runs a database server” / “remote desktop”
What you see
The build is refused before it starts.
Why
Your Dockerfile installs a database server (MySQL, PostgreSQL, MongoDB…) or a remote desktop (VNC, Openbox).
Fix
Remove it from the Dockerfile. For a database, create a managed database and link it: your data survives every deploy.
“This failed on our side, not in your code”
When the build fails because of DockHosting (a build server busy or unreachable), the deploy says so and tries again by itself. If it keeps failing, check the status page or open a ticket.