Next.js build hangs indefinitely because of the telemetry API: root cause, fix, and prevention

A Next.js build that never finishes is usually not a compiler problem at all—it is often a process waiting on the telemetry pipeline to resolve. In this issue, the build appears stuck indefinitely because a background telemetry call does not exit cleanly, leaving the Node.js process alive and making CI, Docker builds, and local production builds look frozen.

You can review the reproduction linked from the original issue in the Next.js reproduction template.

Understanding the Root Cause

Next.js collects anonymous telemetry data unless it is explicitly disabled. Under normal conditions, this reporting is lightweight and should not block a build. The problem appears when the telemetry layer opens or waits on asynchronous work that does not terminate correctly in a specific environment.

Technically, the hang happens because the build process reaches the point where compilation is done, but the underlying Node.js event loop still has active work. That work may be tied to:

• a pending network request to the telemetry endpoint,
• a socket or HTTP keep-alive connection that remains open,
• environment-specific DNS, proxy, or firewall interference,
• CI/container runtime behavior that prevents the process from closing cleanly.

When that happens, next build looks finished from a logging perspective, but the process never exits. This is why the issue is especially visible in CI pipelines, Docker builds, isolated corporate networks, or machines with strict outbound network rules.

In short: the build is not hanging on application code generation; it is hanging because telemetry-related async work keeps the process alive.

Step-by-Step Solution

The most reliable fix is to disable Next.js telemetry for the affected environment so the build does not attempt the problematic API interaction.

1. Disable telemetry globally on the machine or build image

Run this once in the environment where builds execute:

npx next telemetry disable

You can verify the current status with:

npx next telemetry status

2. Disable telemetry explicitly in CI

For CI systems, set the environment variable so every build is deterministic:

NEXT_TELEMETRY_DISABLED=1 next build

Example for package.json:

{
  "scripts": {
    "build": "NEXT_TELEMETRY_DISABLED=1 next build"
  }
}

If you need cross-platform compatibility, especially on Windows, use cross-env:

npm install --save-dev cross-env

{
  "scripts": {
    "build": "cross-env NEXT_TELEMETRY_DISABLED=1 next build"
  }
}

3. Add the environment variable to Docker builds

If the issue happens during container builds, define the variable in the Dockerfile:

FROM node:20-alpine

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

This ensures the image build does not depend on outbound access to telemetry services.

4. Configure CI providers directly

Set NEXT_TELEMETRY_DISABLED=1 in your pipeline configuration.

Example for GitHub Actions:

name: build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NEXT_TELEMETRY_DISABLED: 1
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build

5. Confirm the process now exits cleanly

After disabling telemetry, rerun the build:

npm run build

If telemetry was the cause, the build should complete and the shell should return immediately instead of hanging.

6. Optional: upgrade Next.js

If you are on an older release, test the latest stable version of Next.js because telemetry and process-exit behavior may already be improved in newer versions.

npm install next@latest react@latest react-dom@latest

Then rebuild:

npm run build

7. If you must keep telemetry enabled, inspect the network path

In teams that require telemetry to remain on, check for:

• corporate proxies,
• egress firewalls,
• blocked DNS resolution,
• custom CA certificate issues,
• container networking restrictions.

Those conditions can cause the telemetry request to stall rather than fail fast.

Common Edge Cases

Build still hangs after disabling telemetry

If the process still does not exit, another open handle may be responsible. Common examples include:

• database connections initialized during build-time code execution,
• custom scripts in postbuild,
• plugins spawning long-lived child processes,
• network calls in getStaticProps or build hooks that never resolve.

In that case, telemetry may have exposed the symptom, but not be the only issue.

Windows shell does not recognize inline env vars

NEXT_TELEMETRY_DISABLED=1 next build works in POSIX shells but not in default Windows command shells. Use cross-env or define the variable in the CI environment instead.

Telemetry is disabled locally but CI still hangs

The next telemetry disable command updates the setting for that environment. Your local machine and CI runner are separate environments, so CI still needs its own configuration.

Monorepo builds behave inconsistently

In a monorepo, one package may disable telemetry while another build job runs without that environment variable. Make sure the variable is applied at the workflow or root build orchestration level.

Docker cache masks configuration changes

If you add ENV NEXT_TELEMETRY_DISABLED=1 but still see old behavior, rebuild without stale layers or confirm the variable is defined before the build step.

docker build --no-cache -t my-next-app .

FAQ

Does disabling telemetry affect the functionality of my Next.js app?

No. Disabling telemetry only stops anonymous usage reporting. It does not change routing, rendering, bundling output, or runtime behavior of your application.

Why does the build compile successfully but never exit?

Because successful compilation and process termination are different stages. The build output may be finished, but an unresolved async operation—here, the telemetry API path—can keep the Node.js process alive.

Should I disable telemetry permanently in production CI?

For teams that prioritize reproducible builds, yes—this is a practical and common choice. Setting NEXT_TELEMETRY_DISABLED=1 in CI removes one external dependency from the build pipeline and helps avoid network-related hangs.

The safest production-grade fix for this issue is simple: disable Next.js telemetry in every automated build environment, then verify whether the process exits normally. If it does, you have isolated the hang to the telemetry layer and made your build pipeline more deterministic.