DeployVeraDocs

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.

Last reviewed: Markdown

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.