GitHub Codespaces - When Shit Goes Wrong (And How to Fix It)

Your codespace just crashed with ENOSPC: no space left on device during npm install. Docker layers are eating your disk space faster than you can delete them. Here's what actually works.

The Quick Fix (Nuclear Option)

When you're getting the disk space error, this will save your ass right now:

docker system prune -a --force
docker builder prune --all --force

This nukes everything Docker-related and frees up 5-10GB instantly. You'll have to rebuild your containers, but at least you can work.

Why This Keeps Happening

GitHub gives you 32GB of disk space per codespace, which sounds like plenty until you realize:

• Docker layers stack up: Every RUN command in your Dockerfile creates a new layer. Build your container 5 times? You just used 15GB without realizing it per Docker's layered architecture.
• Node modules multiply: Multiple projects mean multiple node_modules directories. Each one can easily hit 500MB-1GB with dependency bloat.
• Build artifacts accumulate: Webpack outputs, compiled binaries, test coverage reports—they don't clean themselves up automatically.

The Real Solution: Devcontainer Optimization

Edit your .devcontainer/devcontainer.json to include cleanup commands:

{
  "initializeCommand": "docker system prune --force",
  "postCreateCommand": "npm ci && npm run build",
  "shutdownAction": "stopContainer"
}

The initializeCommand runs before your container starts, cleaning up leftover Docker garbage. This prevented me from hitting the disk limit for 3 months straight.

Storage Monitoring That Actually Works

Add this to your shell startup file (.bashrc or .zshrc):

## Check disk space on every terminal start
df -h | grep -E "Size|/$" && echo "Docker space:" && docker system df

Now you'll see exactly how much space you have left every time you open a terminal. When Docker is using more than 10GB, it's time to run docker system prune with proper cleanup strategies.

Docker Layer Hell: The Specific Fix

If you're building Docker images inside Codespaces (yes, Docker-in-Docker), your .devcontainer/Dockerfile is probably wasteful following anti-patterns:

BAD (creates 5 layers):

RUN apt-get update
RUN apt-get install -y git
RUN apt-get install -y curl
RUN apt-get install -y vim
RUN apt-get clean

GOOD (creates 1 layer):

RUN apt-get update \
    && apt-get install -y git curl vim \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

This single change reduced my container size from 2.1GB to 800MB following Docker layer optimization. Multiply that by 10 rebuilds and you just saved 13GB per storage efficiency guidelines.

The npm/yarn Storage Bomb

Node.js projects are the worst offenders. Here's the pattern that kills storage:

1. npm install downloads 300MB of dependencies
2. Rebuild container → npm install again → another 300MB
3. Switch branches → npm install → another 300MB
4. Repeat until dead

Solution: Use npm/yarn cache properly in your devcontainer:

{
  "mounts": [
    "source=node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume"
  ],
  "postCreateCommand": "npm ci"
}

This mounts node_modules as a Docker volume, so it persists between container rebuilds. One npm install, reused forever.

The Machine Type Trap

Upgrading to 4-core or 8-core machines gives you more disk space:

• 2-core: 32GB storage
• 4-core: 64GB storage
• 8-core: 128GB storage

But here's the gotcha: bigger machines don't fix wasteful Docker usage. I've seen developers burn through 128GB in a week by not cleaning up layers.

Fix your Docker hygiene first, then upgrade machine size if you legitimately need more space.

When Storage Monitoring Saves Your Ass

Set up automatic cleanup in your devcontainer configuration:

{
  "initializeCommand": [
    "bash -c 'USED=$(df / | tail -1 | awk \"{print \$5}\" | sed \"s/%//\"); if [ $USED -gt 80 ]; then docker system prune -f; fi'"
  ]
}

This automatically runs docker system prune if disk usage goes above 80%. Saved me from the "no space left" error at least a dozen times.

Your codespace takes 5 minutes to start. VS Code is laggy as hell. npm install runs slower than on your local machine from 2019. Here's what's actually broken and how to fix it.

The Prebuild Trap

Everyone says "use prebuilds" but nobody explains the gotcha: prebuilds are region-specific. If GitHub spins up your codespace in a different Azure region than where your prebuild ran, you get no benefit. You're back to cold-starting every damn time per GitHub's regional limitations.

The fix is forcing your codespace region in your organization settings, but you need GitHub Team or Enterprise for this. Individual accounts get whatever region GitHub feels like per account limitations.

{
  "prebuild": {
    "commands": [
      "npm ci",
      "npm run build"
    ],
    "trigger": {
      "pullRequest": true,
      "push": true
    }
  }
}

But here's the thing: if your npm ci takes longer than 45 minutes, the prebuild times out and fails silently. Check your prebuild logs because they probably failed weeks ago per GitHub Actions timeout behavior.

RAM Starvation on 2-Core Machines

The default 2-core machine gives you 4GB RAM. That sounds fine until your React app needs 2GB, your database needs 1GB, and VS Code wants another 1GB. Now you're swapping to disk constantly per memory constraints.

Don't upgrade your machine type immediately. First, check what's actually using memory with system monitoring:

## See which processes are memory hogs
ps aux --sort=-%mem | head -10

## Check if you're swapping
free -h

Common memory killers in development:

• Webpack dev server: Can use 1-2GB with source maps
• Jest watch mode: Keeps test files in memory indefinitely
• Multiple Node processes: Each npm start in different projects
• Docker builds: Can temporarily spike to 3-4GB

The quick fix for Node.js memory issues:

export NODE_OPTIONS="--max-old-space-size=2048"

This limits Node to 2GB instead of trying to use all available RAM.

The Network Performance Cliff

Your internet speed doesn't matter once you're inside the codespace, but your latency to GitHub's servers does. If you're in Australia connecting to a US East codespace, every keystroke has 200ms lag.

There's no perfect solution, but you can minimize the pain:

1. Use GitHub CLI for commits: gh commands are faster than VS Code's Git integration
2. Batch file operations: Copy-paste multiple files instead of one-by-one saves
3. Use local VS Code: Desktop VS Code connecting to codespaces has less network overhead than browser VS Code

Docker Build Performance Disasters

Building Docker images inside Codespaces is 3-5x slower than local because of the virtualization overhead. But the real killer is not using BuildKit.

Add this to your .devcontainer/devcontainer.json:

{
  "initializeCommand": "export DOCKER_BUILDKIT=1",
  "build": {
    "dockerfile": "Dockerfile",
    "options": ["--progress=plain"]
  }
}

BuildKit enables parallel layer builds and better caching. I've seen 15-minute builds drop to 3 minutes with this alone.

The Extension Performance Killer

VS Code extensions run on your codespace's CPU, not your local machine. Heavy extensions can make everything sluggish:

Performance killers:

• Auto-formatting on every keystroke
• Real-time linting for large files
• AI coding assistants (GitHub Copilot uses 10-20% CPU constantly)
• Language servers for large codebases

Quick fix: Disable extensions you don't need in your devcontainer:

{
  "extensions": [
    "ms-python.python"
  ],
  "settings": {
    "editor.formatOnSave": false,
    "editor.formatOnType": false
  }
}

Database Performance: The Connection Pool Problem

If your app is connecting to a database inside the codespace, you're probably not using connection pooling. Every new HTTP request creates a new DB connection, which is slow and eventually hits connection limits.

For Node.js apps using PostgreSQL:

// BAD: New connection per request
const client = new Client({
  host: 'localhost',
  user: 'postgres',
  password: 'password'
});

// GOOD: Connection pool
const { Pool } = require('pg');
const pool = new Pool({
  host: 'localhost',
  user: 'postgres', 
  password: 'password',
  max: 10, // Maximum connections
  idleTimeoutMillis: 30000
});

This single change took my API response times from 800ms to 50ms.

The File Watcher Explosion

VS Code watches all files in your workspace for changes. In a large monorepo, this can be thousands of files. Each file watch uses CPU and memory.

Solution: Configure VS Code to ignore directories you don't care about:

{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/build/**": true,
    "**/.git/**": true
  }
}

This reduced my CPU usage from 60% to 15% in a 50,000-file repository.

When Upgrading Machine Type Actually Helps

Upgrade from 2-core to 4-core when:

• Your npm install consistently takes over 5 minutes
• Docker builds take over 10 minutes
• You're running 3+ services simultaneously (app, database, Redis, etc.)
• VS Code becomes unresponsive during file saves

Don't upgrade for:

• Network lag issues (won't help)
• Storage problems (fix Docker hygiene first)
• Single-threaded processes (more cores won't speed up pip install)

The Cost vs Performance Reality

4-core machines cost 2x as much but aren't always 2x faster. Profile your actual bottlenecks first:

## Check CPU usage during your slowest operations
top -p $(pgrep -f "npm|node|python|docker")

## Check disk I/O (often the real bottleneck)
iostat -x 1

If CPU usage stays under 70% during slow operations, more cores won't help. You probably have a disk I/O or network bottleneck instead.