Troubleshooting dev containers

Dev container not starting

If your dev container fails to start:

1. Check the agent logs for error messages:

   • /tmp/coder-agent.log
   • /tmp/coder-startup-script.log
   • /tmp/coder-script-[script_id].log

2. Verify Docker is available in your workspace (see below).

3. Ensure the devcontainer.json file is valid JSON.

4. Check that the repository has been cloned correctly.

5. Verify the resource limits in your workspace are sufficient.

Docker not available

Dev containers require Docker, either via a running daemon (Docker-in-Docker) or a mounted socket from the host. Your template determines which approach is used.

If using Docker-in-Docker, check that the daemon is running:

If using a mounted socket, verify the socket exists and is accessible:

If you get permission errors, your user may need to be in the docker group.

Finding your dev container agent

Use coder show to list all agents in your workspace, including dev container sub-agents:

The agent name is derived from the workspace folder path. For details on how names are generated, see Agent naming.

SSH connection issues

If coder ssh <workspace>.<agent> fails:

1. Verify the agent name using coder show <workspace>.

2. Check that the dev container is running:

   docker ps

3. Check the workspace agent logs for container-related errors:

   grep -i container /tmp/coder-agent.log

VS Code connection issues

VS Code connects to dev containers through the Coder extension. The extension uses the sub-agent information to route connections through the parent workspace agent to the dev container. If VS Code fails to connect:

1. Ensure you have the latest Coder VS Code extension.
2. Verify the dev container is running in the Coder dashboard.
3. Check the parent workspace agent is healthy.
4. Try restarting the dev container from the dashboard.

Dev container features not working

If features from your devcontainer.json aren't being applied:

1. Rebuild the container to ensure features are installed fresh.

2. Check the container build output for feature installation errors.

3. Verify the feature reference format is correct:

   { "features": { "ghcr.io/devcontainers/features/node:1": {} } }

Slow container startup

If your dev container takes a long time to start:

1. Use a pre-built image instead of building from a Dockerfile. This avoids the image build step, though features and lifecycle scripts still run.
2. Minimize features. Each feature executes as a separate Docker layer during the image build, which is typically the slowest part. Changing devcontainer.json invalidates the layer cache, causing features to reinstall on rebuild.
3. Check lifecycle scripts. Commands in postStartCommand run on every container start. Commands in postCreateCommand run once per build, so they execute again after each rebuild.

Getting more help

If you continue to experience issues:

1. Collect logs from /tmp/coder-agent.log (both workspace and container).
2. Note the exact error messages.
3. Check Coder GitHub issues for similar problems.
4. Contact your Coder administrator for template-specific issues.