Troubleshooting-build-failures

By NEXUS AI Team · Contact: nexusai.run/contact

This document covers the most common build failures on NEXUS AI, how to diagnose them from logs, and the exact fix for each.

Table of contents

1. How to read build logs
2. npm install failed (exit code 1)
3. Next.js: build command resolves to none
4. Next.js: running next dev in production
5. Private npm packages failing to install
6. Node version mismatch
7. Docker build timeout
8. General diagnosis checklist

How to read build logs

Every failed deployment writes structured logs. The key fields to look at:

level: error
message: Build error detail: The command '...' returned a non-zero code: 1
code: 1

The message field contains the exact build command that failed. The code field is the exit code — 1 means the command itself failed, not a timeout or network error.

To see the full npm output (including the actual error npm printed before it stopped), pull the build logs from the dashboard or CLI:

nexus deploy logs <deployment-name> --build

This streams the complete build output including every line npm printed before it failed — that output is what tells you the actual cause.

npm install failed (exit code 1)

What it looks like

Build error detail: The command '/bin/sh -c if [ -f package-lock.json ];
then npm ci || npm ci --legacy-peer-deps; else npm install || npm install
--legacy-peer-deps; fi' returned a non-zero code: 1

What NEXUS AI does

NEXUS AI generates a Dockerfile for your app automatically. During the build, it runs:

if [ -f package-lock.json ]; then
  npm ci || npm ci --legacy-peer-deps
else
  npm install || npm install --legacy-peer-deps
fi

If package-lock.json is present, it tries npm ci first (strict install from lockfile), then falls back to npm ci --legacy-peer-deps (relaxed peer dependency resolution). If both fail, the build aborts with exit code 1.

Root causes and fixes

Cause 1: package-lock.json is out of sync with package.json

Signal: Both npm ci and npm ci --legacy-peer-deps fail. The lockfile exists but was generated in a different state than the current package.json.

How this happens: You added or removed a package locally but did not commit the updated package-lock.json, or the lockfile was generated on a different OS or Node version.

Fix: Regenerate the lockfile locally and commit it.

rm package-lock.json
npm install
git add package-lock.json
git commit -m "regenerate package-lock.json"

Then redeploy:

nexus deploy redeploy <deployment-name>

Cause 2: Dependency conflict beyond --legacy-peer-deps

Signal: npm prints peer dependency errors even with --legacy-peer-deps. Common with packages that have conflicting React or TypeScript version requirements.

How this happens: Two or more packages in your dependency tree declare incompatible peer dependencies that cannot be reconciled even with relaxed resolution.

Fix: Identify the conflicting packages from the npm output (look for lines starting with ERESOLVE or peer dep missing) and either:

• Pin one of the conflicting packages to a compatible version in package.json
• Use overrides in package.json to force a specific version:

{
  "overrides": {
    "some-package": "^3.0.0"
  }
}

Then delete package-lock.json, run npm install locally, commit the result, and redeploy.

Cause 3: Transient npm registry failure

Signal: The build log shows ECONNRESET, ETIMEDOUT, network error, or 503 from the registry.

How this happens: The npm registry was temporarily unavailable during the build.

Fix: Retry the deployment — these failures are transient.

nexus deploy redeploy <deployment-name>

If failures persist across multiple retries, check status.npmjs.com for registry incidents.

Cause 4: Corrupted package-lock.json

Signal: npm output shows Invalid package-lock.json or a JSON parse error.

Fix:

rm -rf package-lock.json node_modules
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"

Next.js: build command resolves to none

What it looks like

Resolved commands - build: none, start: next dev -H 0.0.0.0

What's happening

NEXUS AI detected your app as Next.js but could not find a build script in your package.json. Without a build script, it cannot run next build and skips the build step entirely, falling back to the development server at runtime.

Fix

Add build and start scripts to package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -H 0.0.0.0 -p 3000"
  }
}

NEXUS AI reads scripts.build and scripts.start to determine how to build and run your app. Both must be present for a correct production deployment.

Commit the change and redeploy:

git add package.json
git commit -m "fix: add build and start scripts for production"
nexus deploy redeploy <deployment-name>

Next.js: running next dev in production

What it looks like

Resolved commands - build: none, start: next dev -H 0.0.0.0

Why this is a problem

next dev is the development server. Running it in production causes:

• No build optimization — pages compile on every request
• Source maps exposed in the browser
• Significantly higher memory usage — full TypeScript and Babel compiler loaded at runtime
• Slower response times under load
• Hot-reloading overhead with no benefit

Fix

Ensure package.json has the correct scripts:

{
  "scripts": {
    "build": "next build",
    "start": "next start -H 0.0.0.0 -p 3000"
  }
}

With both scripts present, NEXUS AI will run next build at build time and next start at runtime — the correct production path.

Private npm packages failing to install

What it looks like

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/@your-org/package

or

npm error code E403
npm error 403 Forbidden

What's happening

Your project depends on packages from a private npm registry (GitHub Packages, a private npm org, Artifactory, etc.). The build environment has no credentials to access them.

Fix

Step 1 — Store your npm token as a NEXUS AI secret:

nexus secret set NPM_TOKEN "your-npm-token-here" --environment production

Step 2 — Add a .npmrc file to the root of your project:

# For npm private registry
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# For GitHub Packages
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
@your-org:registry=https://npm.pkg.github.com

NEXUS AI injects NPM_TOKEN into the build environment at build time. npm reads it from .npmrc automatically during install.

Step 3 — Commit .npmrc and redeploy:

git add .npmrc
git commit -m "add .npmrc for private package auth"
nexus deploy redeploy <deployment-name>

Note: Do not put the actual token value in .npmrc — use ${NPM_TOKEN} as shown. The actual value lives in the NEXUS AI secrets vault and is injected at build time.

Node version mismatch

What it looks like

npm warn EBADENGINE Unsupported engine {
  package: '[email protected]',
  required: { node: '>=20.0.0' },
  current: { node: 'v18.x.x' }
}

or native module build errors:

gyp ERR! build error
node-pre-gyp ERR! build error

What's happening

A dependency requires a Node version higher (or lower) than the version in the build environment, or a native module fails to compile because system build tools are missing.

Fix option A — Declare a Node version requirement in package.json:

{
  "engines": {
    "node": ">=20.0.0"
  }
}

NEXUS AI reads the engines.node field and selects the appropriate base image when possible.

Fix option B — Pin the exact Node version with .nvmrc:

20.11.0

Add a .nvmrc file to your project root. NEXUS AI uses this to select the correct Node version for your build.

Fix option C — For native modules (sharp, canvas, bcrypt, argon2)

These modules require native build tools (python3, make, g++). NEXUS AI automatically detects and installs build dependencies for known native modules. If your native module is not detected:

Add it explicitly to your package.json so NEXUS AI can identify the requirement, or contact support with your deployment ID and the full build log.

Docker build timeout

What it looks like

level: error
code: 137
message: Build error event

Exit code 137 means the process was killed — typically an OOM (out of memory) kill during the build.

Common causes

• Very large dependency trees (monorepos, 500+ packages)
• Native module compilation consuming excessive memory during build
• next build running out of memory on large Next.js apps

Fix option A — Add a .dockerignore to reduce build context size:

node_modules
.next
dist
build
.git
*.log
coverage
.env*
.env.local
.env.production

This prevents large directories from being sent to the build context, significantly reducing build time and memory usage.

Fix option B — Increase Next.js build memory:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

Fix option C — Use Next.js standalone output mode:

In next.config.js:

module.exports = {
  output: 'standalone',
};

Standalone mode produces a self-contained build output that copies only necessary files, reducing the final image size and build memory requirements significantly.

General diagnosis checklist

Run through this before opening a support ticket:

• [ ] Pull full build logs via the dashboard or nexus deploy logs <name> --build
• [ ] Read the exact npm error line above the exit code — that line contains the actual cause
• [ ] Confirm package-lock.json is committed and reflects the current package.json
• [ ] Confirm package.json has both a build script and a start script
• [ ] Confirm start script uses next start (not next dev) for Next.js apps
• [ ] Check if any dependency is from a private registry (look for @org/ scoped packages)
• [ ] Confirm npm install succeeds on a clean node_modules on your local machine
• [ ] Add .dockerignore to exclude node_modules, .next, dist from the build context
• [ ] Retry once after a failed build — transient npm registry failures resolve on redeploy
• [ ] If none of the above resolves it, open a support ticket with your deployment ID and the full build log output

For issues not covered here, use the in-app support or open a ticket at nexusai.run. Include your deployment ID and the output of the build logs.

Start for free · Read the documentation · About NEXUS AI · Contact