Claude Code Dev Containers

Troubleshooting Guide

🔧 Troubleshooting

Solutions to common development container issues and errors

❌ Error: "Cannot connect to Docker daemon"

Cause: Docker Desktop isn't running.

Solution:

  1. Start Docker Desktop from your Applications folder
  2. Wait for the whale icon in your menu bar/system tray to show it's running
  3. Retry in VS Code: Cmd+Shift+P → "Dev Containers: Rebuild Container"

❌ Error: "Command not found" (npm, python, etc.)

Cause: Tool not installed in the container, or PATH not set correctly.

Solution:

  1. Check your Dockerfile has the correct base image (e.g., FROM node:22)
  2. Rebuild the container: Cmd+Shift+P → "Dev Containers: Rebuild Container"
  3. If still failing, check you're using the correct terminal (should say "Dev Container" in bottom-left)

⚠ī¸ Container is very slow

Cause: Docker performance issues, especially on Mac/Windows.

Solutions:

  • Mac: Enable VirtioFS in Docker Desktop → Settings → Experimental Features
  • Windows: Ensure project is in WSL2 filesystem, not /mnt/c/
  • Use named volumes for node_modules: Add to mounts: "source=node-modules,target=/workspace/node_modules,type=volume"
  • Create .dockerignore file to exclude node_modules, .git from build context

ℹī¸ Port already in use

Cause: Another process is using the port (e.g., 3000, 5000).

Solutions:

  1. Find what's using the port: lsof -i :3000 (Mac/Linux) or netstat -ano | findstr :3000 (Windows)
  2. Kill the process or change your app's port
  3. Update forwardPorts in devcontainer.json to match new port

❌ Codex CLI: Landlock Sandbox Error

thread 'main' panicked at linux-sandbox/src/linux_run_main.rs:30:9:

error running landlock: Sandbox(LandlockRestrict)

Cause: Docker's LinuxKit kernel doesn't support Landlock (Linux security module). This is a known limitation of containerized environments.

Solution: Disable Codex sandboxing (safe in containers):

~/.codex/config.toml 

sandbox_mode = "danger-full-access"
approval_policy = "never"

✅ Why This Is Safe:

  • Docker container provides process isolation
  • Network firewall restricts connections
  • Non-root user execution (node)
  • OpenAI's official recommendation for Docker

Verify it works: 

codex --version
codex exec "echo 'Hello from Codex'"

📝 Note: This repository's devcontainer automatically applies this fix via init-codex-config.sh. Configuration persists across container rebuilds.

⚠ī¸ IMPORTANT: VSCode Extension Limitation

The above configuration only works for Codex CLI, not the VSCode extension.

VSCode Extension Issue:

  • Extension ignores sandbox_mode in config.toml
  • Only reads model and model_reasoning_effort
  • Always tries to use Landlock sandbox (fails in Docker)
  • Tracked as GitHub Issue #5041

✅ Workaround:

Use Codex CLI instead of VSCode extension: 

codex exec "your prompt here"

Status: OpenAI is working on adding config.toml support to the extension. No ETA available. CLI works perfectly.

❌ OpenCode: TUI Crashes When Loading Models

TypeError: undefined is not an object (evaluating 'flat().length')

at <anonymous> (src/cli/cmd/tui/ui/dialog-select.tsx:49:49)

Cause: OpenCode's auth.json contains provider configurations incompatible with AI SDK v5. The cloudflare-workers-ai provider doesn't support specification v2 required by SDK v5, and expired OAuth tokens (github-copilot) return undefined when queried, causing the dialog component to crash when attempting to flatten provider data.

Solution:

1. Backup current configuration 

cp ~/.local/share/opencode/auth.json \
   ~/.local/share/opencode/auth.json.backup

2. Remove incompatible providers from auth.json 

nano ~/.local/share/opencode/auth.json

Keep only: anthropic, openrouter, nvidia, openai, google

3. Clear stale cache 

rm -rf ~/.cache/opencode/*

4. Verify operation 

opencode models  # Should display 180+ models
opencode         # TUI should start without errors

💡 Why This Works

  • Removes provider entries that return undefined when queried
  • Clears cached model metadata referencing removed providers
  • Allows OpenCode to rebuild provider list from scratch

✅ Compatible Providers

  • anthropic, openai, google (primary providers)
  • openrouter, nvidia (third-party aggregators)

❌ Known Incompatible Providers

  • cloudflare-workers-ai (doesn't support AI SDK v5)
  • requesty (similar SDK incompatibility - Issue #2468)
  • github-copilot (OAuth flow incompatible with devcontainers)

🔧 Prevention Tips

  • Only authenticate with actively maintained providers
  • Periodically review auth.json and remove unused/expired providers
  • Keep OpenCode updated: npm update -g @opencode-ai/opencode

❌ Docker Build: Permission Denied in .config Directory

mkdir: cannot create directory '/home/node/.config/fish': Permission denied

ERROR: command failed: mkdir -p /home/node/.config/fish

Cause: Setting ownership on a subdirectory (like .config/gh) instead of the parent directory (.config) leaves the parent owned by root. When installers (uv, fish, zsh) try to create their own subdirectories, they fail due to permission errors.

Root Cause Explanation:

  • mkdir -p /home/node/.config/gh creates both parent and subdirectory
  • Parent directory .config is owned by root
  • chown on subdirectory only affects that subdirectory
  • Later installers cannot create new subdirectories in root-owned parent

❌ Incorrect (in Dockerfile): 

RUN mkdir -p /home/node/.config/gh /home/node/.claude && \
  chown -R node:node /home/node/.config/gh  # Only owns subdirectory!

✅ Correct (in Dockerfile): 

RUN mkdir -p /home/node/.config/gh /home/node/.claude && \
  chown -R node:node /home/node/.config  # Owns entire .config tree!

💡 Pattern to remember:

  • ❌ chown -R user /path/parent/child (only owns child)
  • ✅ chown -R user /path/parent (owns parent + all children)

Verification commands: 

# Check parent directory ownership
ls -ld /home/node/.config
# Should show: drwxr-xr-x node node

# Test creating new subdirectory as node user
su - node -c "mkdir -p /home/node/.config/test"
# Should succeed without permission errors

⚠ī¸ When you see this: Permission errors during RUN commands that create files in ~/.config, installers like uv/fish/zsh failing, or build succeeding up to a point then failing on config directory creation.

💡 Quick Debug Commands 

# Check Docker is running
docker ps

# Check container logs
docker logs <container-name>

# View Docker disk usage
docker system df

# Clean up unused images/containers (frees space)
docker system prune -a

# Restart Docker Desktop
# Mac: Click whale icon → Quit → Relaunch
# Windows: Right-click whale icon → Quit → Relaunch