TECHNICAL REFERENCE
Build errors and fixes
Common build failures: how they look in the log, why they happen, how to fix them in DeployVera and how to verify.
How to read this
When a build fails, open the build log in the panel and find the first real error line; the trailing exit code: 1 is only a summary. The sections below start with the most common failures. Log lines are generic examples; names in your own log will differ.
Compile errors (especially Next.js)
In the log: Type error: ..., Failed to compile. or process "npm run build" did not complete successfully: exit code: 1.
Why it happens: next build stops on TypeScript and ESLint errors that the local npm run dev may not show. Case-sensitive import paths on Linux (./UserCard vs ./usercard) and packages missing from package.json also break the build.
- Run
npm ci && npm run buildin a clean local clone and fix the errors; do not silence types withany. - For
Module not found, match the import casing to the file name and add the package withnpm install <package>. - Add variables needed at build time (for example
NEXT_PUBLIC_*) under Environment variables; they are inlined at build, so rebuild after changing them. - Push the change and redeploy.
- Verify:
npm run buildexits 0 locally and the new build reaches 'Live' in the panel.
Tip: Next.js
Most Next.js build failures are avoided by four things: output: 'standalone' in next.config; Port and the environment variable PORT=3000 in the panel; HOSTNAME=0.0.0.0; and fixing TypeScript errors locally with npm run build before you push.
// next.config.ts
export default { output: 'standalone' };
// Environment variables
// PORT=3000
// HOSTNAME=0.0.0.0Node.js version mismatch
In the log: Unsupported engine, EBADENGINE or Node.js v22.11.0 is not supported.
Why it happens: a dependency or tool needs a newer Node.js than the automatic (Nixpacks) build provides by default.
- Add
NIXPACKS_NODE_VERSION=22under Environment variables and keepengines.nodein package.json consistent. - If you need a minor version, add
nixpacks.tomlat the repository root and pin the nixpkgs archive (details in the Quickstart article), or switch to the Dockerfile method under Build and runtime settings and use an exact image such asFROM node:22.12-slim. - Verify: the engine error no longer appears on redeploy.
Database unreachable
In the log: P1001: Can't reach database server, ECONNREFUSED or a prisma migrate deploy error at start.
Why it happens: DATABASE_URL is missing or wrong, or the database was not created in the same service.
- Add a managed database to the service; applications and databases in one service reach each other over a private network.
- Add the connection string as
DATABASE_URLunder Environment variables. - If you run migrations in the start command and the error persists, split them out of it.
- Verify: the start log shows the migration completing and the container becomes healthy.
Container not healthy (port)
In the log: New container is not healthy, rolling back to the old container or EADDRINUSE.
Why it happens: the app is not listening on 0.0.0.0:$PORT; it listens on localhost only, uses a hard-coded port, or the Port field in the panel is wrong.
- Make the app listen on
process.env.PORTand0.0.0.0. - Match the Port field in the panel with the app's port.
- Verify: the new version becomes healthy and is not rolled back.
Configuration error (Dockerfile, branch, environment variables)
In the log: failed to compute cache key: "/file": not found, Remote branch ... not found or Missing required environment variable.
Why it happens: a COPY in the Dockerfile points at a file that is not in the repository, the selected branch does not exist, or a required variable is unset.
- Check
COPYpaths against the repository root; confirm the file is committed and not in.dockerignore. - Match the branch under Build and runtime settings with a real branch name.
- Add the variables named in the log under Environment variables.
- Verify: the error line is gone from the log.
Missing start command / process exits right away
In the log: Missing script: "start", No start command could be found or a container restarting with exit code=0.
Why it happens: package.json has no start script, the Dockerfile has no CMD, or the command runs and exits immediately.
- Add a
startscript to package.json that keeps the server running. - If you use a Dockerfile, add a final
CMD [...]. - Check the start command under Build and runtime settings is not empty or wrong.
- Verify: the container stays running and the log shows the server listening.
Repository access failed
In the log: Authentication failed, Repository not found or Permission denied (publickey).
Why it happens: the Git connection was revoked, or the repository was deleted or made private.
- Re-authorize the Git account in the panel.
- Check the repository name and branch; for a private repository the account needs read access.
- Verify: the repository is fetched without errors in the first log step.
Other common errors
- Native dependency:
apt-get install ... did not complete successfully. Verify the package name; use the Dockerfile method for complex system dependencies. - DNS:
getaddrinfo EAI_AGAIN/ENOTFOUND <host>. Check the host name and the addresses in your environment variables. - Write permission:
EACCESorEROFS(for example/data). Give the directory to the app user; attach a volume for files that must persist and use/tmpfor temporary files.
Platform-side errors
Some failures come from the platform, not your code: a 504 from the internal Git proxy or being unable to reach the Git host, and transient transfer drops such as fatal: early EOF.
What to do: wait a few minutes and redeploy; do not change code or settings. If it repeats, open a support ticket and include the build ID.
Speeding up the build
If builds are slow, see /docs/en/faster-builds for how the cache works, Dockerfile layer order and cache mount points.