Files
coder/docs/user-guides/devcontainers/troubleshooting-dev-containers.md
T
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary

**Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`). Adds a front-matter `title` to every navigable docs
page whose title can be migrated **mechanically**, with no editorial
judgment.

This is the content step that Phase 1 (renderers prefer front-matter
title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware,
`DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged
and live.

**Rendered no-op.** The renderers already resolve the page title from
the manifest and hide the leading body H1 (Phase 1), so no page changes
visually. This just moves the title into front matter where Fumadocs and
the migrated tooling can read it.

## What's in this batch

Dry-run on `main` (464 navigable pages) splits into:

| category | count | this PR |
|----------|-------|---------|
| already has front-matter title (Reference, from Phase 2 generators) |
196 | skipped (idempotent) |
| **mechanical** — leading body H1 equals the manifest label | 138 | ✅
add front-matter `title`, drop the duplicate H1 |
| **no body H1** — renders under the manifest label only | 4 | ✅ add
front-matter `title` only |
| **mismatch** — body H1 differs from the manifest label | 126 | ⏭️
deferred (needs an editorial decision, see below) |

142 files changed, all under `docs/`.

## Deliberately out of scope: the 126 mismatches

Pages where the body H1 is richer than the short sidebar label (e.g.
label **Modules** / H1 *Contributing modules*, label **Install** / H1
*Installing Coder*) need a canonical-title decision, not a script. A few
even look like the body H1 is the redundant one (`install/cli.md` and
`install/index.md` both carry the H1 *Installing Coder*). These will
land in follow-up batches **by nav section** once the policy is set, so
each gets real review.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Every added front-matter block parses as YAML and its `title`
round-trips to the manifest label (checked programmatically across all
142 files).
- Every removed line is a leading `# H1` that equalled the manifest
title; no body prose was reflowed. Front matter is correctly hoisted
above pre-existing `<!-- markdownlint-disable -->` comments on the two
pages that had them.
- `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the
changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in
Phase 4); `MD025` is not tripped because the duplicate body H1s are
removed.

```
$ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main)
Linting: 142 file(s)
Summary: 0 error(s)
```

Linear: DOCS-484

> This PR was created with AI assistance (Coder Agents).
2026-08-27 12:34:13 -04:00

3.5 KiB

title
title
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:

sudo service docker status
sudo service docker start  # if not running

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

ls -la /var/run/docker.sock
docker ps  # test access

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:

coder show <workspace>

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.