# 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.

Last reviewed: 2026-11-12

## 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 build` in a clean local clone and fix the errors; do not silence types with `any`.
- For `Module not found`, match the import casing to the file name and add the package with `npm 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 build` exits 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.0
```

## Node.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=22` under Environment variables and keep `engines.node` in package.json consistent.
- If you need a minor version, add `nixpacks.toml` at 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 as `FROM 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_URL` under 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.PORT` and `0.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 `COPY` paths 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 `start` script 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: `EACCES` or `EROFS` (for example `/data`). Give the directory to the app user; attach a volume for files that must persist and use `/tmp` for 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.

Sources: https://api.deployvera.com/api/plans · https://deployvera.com/docker · https://deployvera.com/help
