How to reliably debug a Next.js app inside Docker using VSCode (breakpoints will finally hit)

[eodeluga]

Debugging Next.js in Docker with VSCode

This guide explains how to reliably debug a Next.js app running inside a Docker container using Visual Studio Code. This was written through the experience of many hours troubleshooting with ChatGPT, only to make a simple discovery hiding in plain sight (that Next.js console was actually trying to tell me all along 😳)

---

🧠 Key Discovery

Next.js v15+ listens on port 9230 for its internal router debugger when started with --inspect.

However, this port is not automatically exposed from the container. Breakpoints will not be hit unless:

• Port 9230 is explicitly mapped in docker-compose.yml
• You attach VSCode to port 9230, not 9229

---

✅ Final Solution Setup

1. Expose port 9230 in Docker Compose

services:
web:
    container_name: my_next_dev
    image: node:22.14.0-bullseye
    working_dir: /app
    command: 'yarn dev'
    ports:
      - '3000:3000'
      - '9229:9229'
      - '9230:9230'
    volumes:
      - ./:/app

---

2. Use package.json script to launch the debugger properly

⚠️ Do NOT use NODE_OPTIONS in .env or docker-compose.yml. It confuses Next.js.

"scripts": {
  "dev": "NODE_OPTIONS='--inspect=0.0.0.0:9229' next dev"
}

---

3. VSCode launch.json

Attach to port 9230:

{
  "name": "Docker Node.js Launch",
  "type": "node",
  "request": "attach",
  "address": "localhost",
  "port": 9230,
  "localRoot": "${workspaceFolder}/src",
  "remoteRoot": "/app",
  "sourceMaps": true,
  "skipFiles": ["<node_internals>/**"],
  "smartStep": true,
  "trace": true,
  "outputCapture": "std",
  "preLaunchTask": "Start Dev Environment"
}

---

4. VSCode tasks.json

Runs the Docker environment when F5 is pressed:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Dev Environment",
      "type": "shell",
      "command": "./start-dev.sh",
      "problemMatcher": [],
      "detail": "Start the dev environment if not already running",
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "reveal": "always",
        "panel": "shared",
        "clear": true
      },
      "options": {
        "cwd": "${workspaceFolder}"
      }
    }
  ]
}

---

5. start-dev.sh QOL script that builds and starts containers if not already running

#!/bin/bash

set -e

COMPOSE_FILE="docker-compose.dev.yml"
ENV_FILE=".env.docker"

CONTAINERS=("your" "container" "names")

running=false
for name in "${CONTAINERS[@]}"; do
  if docker ps --filter "name=^/${name}$" --format '{{.Names}}' | grep -q .; then
    running=true
    break
  fi
done

if [ "$running" = false ]; then
  echo "🔺 Starting dev environment..."
  docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" up --build -d
fi

---

🔍 Verifying Debugger Is Active

Use:

curl http://localhost:9230/json/list

You should receive a JSON response confirming the debugger is active.