Dev Container Configuration Common Errors and Solutions

Why Dev Container Drives You Crazy

Dev Container (VS Code Remote Development Containers) became a standard development environment for many teams in 2026. Theoretically it solves the "works on my machine" problem, but the configuration phase alone is enough to drive you insane.

After 3 months and countless pitfalls, I compiled the 5 most common configuration traps with specific error messages and solutions.

Pitfall 1: devcontainer.json Port Forwarding Not Working

The Problem

Container starts fine, VS Code connects, but browser just spins at http://localhost:3000 forever.

Debugging Process

# First check if the container is actually listening on the port
docker exec -it  netstat -tlnp | grep 3000
# Output: tcp        0      0 127.0.0.1:3000          0.0.0.0:*              LISTEN

Found it: the service is bound to 127.0.0.1 (inside container), not 0.0.0.0 (all interfaces).

Solution

Edit devcontainer.json:

{
  "forwardPorts": [3000],
  "appPort": 3000
}

Also ensure the app itself listens on 0.0.0.0 (Node.js example):

// server.js
const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Prevention

When creating devcontainer.json, get into the habit of checking what host the app listens on first.

---

Pitfall 2: PostCreateCommand Timing Misunderstanding

The Problem

After running Dev Containers: Rebuild Container, global tools I manually installed before (pnpm, typos) are all gone.

Root Cause

postCreateCommand only runs **once when the container is first created**. Rebuild recreates the container but does not re-trigger postCreateCommand.

Solution

Use postStartCommand instead (runs every time container starts):

{
  "postCreateCommand": "pnpm install",
  "postStartCommand": "pnpm install && echo 'Dependencies ready'"
}

Or better: write dependencies into the Dockerfile so there's nothing to rely on:

# .devcontainer/Dockerfile
FROM node:20
RUN npm install -g pnpm && pnpm install

Prevention

Put all dependency installation in Dockerfile or docker-compose.yml, don't rely on postCreateCommand.

---

Pitfall 3: Data Lost After Container Rebuild

The Problem

After Rebuild Container, the database is empty and local files are gone.

Debugging

# Check docker-compose.yml volumes configuration
cat .devcontainer/docker-compose.yml

The issue is that volumes are not properly mounted, or the mount paths are relative paths that change after rebuild.

Solution

Explicitly specify absolute paths in docker-compose.yml:

services:
  app:
    volumes:
      - ../data:/app/data        # Correct: relative path resolves from compose file directory
      - postgres_data:/var/lib/postgresql/data  # Correct: named volume, persists after rebuild

Avoid anonymous volumes (unnamed volumes get cleared on rebuild).

Prevention

Use named volumes for data that needs to persist, and document in README which directories need backup.

---

Pitfall 4: docker-compose Extensions Format Incompatibility

The Problem

When opening Dev Container in VS Code: Unsupported docker compose version: '3.8'.

Debugging

# Check Docker Compose version
docker-compose version
# Docker Compose version v2.24.0

# Check devcontainer.json compose version
grep -A5 "dockerComposeFile" .devcontainer/devcontainer.json

VS Code's built-in devcontainer CLI version doesn't match the system's Docker Compose version.

Solution

Specify version-compatible config in devcontainer.json:

{
  "dockerComposeFile": [
    "docker-compose.yml"
  ],
  "service": "app",
  "workspaceFolder": "/workspace"
}

Also ensure docker-compose.yml doesn't specify a specific version number (new Compose defaults to backward compatibility):

# Don't write version: '3.8'
services:
  app:
    build: .

Prevention

Run Dev Containers: Rebuild Container regularly to ensure config is compatible with actual environment.

---

Pitfall 5: Personal Config Gets Ignored by .gitignore

The Problem

Team members have inconsistent Dev Container experience — some have terminal color garbling, others get git operation errors.

Root Cause

VS Code Dev Container config is global, but user-specific settings (settings.json, extensions.json) aren't under version control.

Solution

Explicitly specify personal config in devcontainer.json:

{
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.fontSize": 14,
        "editor.formatOnSave": true
      },
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

Also create .vscode/settings.json in project root for team reference:

{
  "editor.tabSize": 2,
  "files.trimTrailingWhitespace": true
}

Prevention

Commit the entire .devcontainer/ directory to git, and document in README the initial startup steps (Dev Containers: Open Folder in Container).

---

Quick Checklist

When creating Dev Container for a new project, check in order:

1. **Port forwarding**: forwardPorts configured + app listens on 0.0.0.0

2. Dependency installation: written in Dockerfile, not postCreateCommand

3. Data persistence: use named volumes for database and important files

4. Compose version: don't specify concrete version or use compatible version

5. Team config: customizations include settings and extensions

---

FAQ

Q: Container won't start after Rebuild?

# Check container logs
docker logs 

# Full Dev Container reset
Dev Containers: Rebuild Without Cache

Q: How to configure multi-container projects?

Use docker-compose.yml extensions field, write all services in one file, devcontainer.json only specifies primary service.

Q: How to share devcontainer config with team?

Commit the entire .devcontainer/ directory to git, and document in README the initial startup steps.

---

If you're using AI Coding Agents (Claude Code, Cline), I recommend first validating the environment in a local Dev Container before syncing to remote servers — avoid debugging nightmares caused by environment inconsistencies.

👉 Try MiniMax API now: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

Disclosure: This article contains affiliate links. I only recommend tools I've personally tested and found valuable.