Files
coder/docs/admin/templates/troubleshooting.md
T
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## 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.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00

9.9 KiB

title
title
Troubleshoot templates

Occasionally, you may run into scenarios where a workspace is created, but the agent is either not connected or the startup script has failed or timed out.

Agent connection issues

If the agent is not connected, it means the agent or init script has failed on the resource.

$ coder ssh myworkspace
⢄⡱ Waiting for connection from [agent]...

While troubleshooting steps vary by resource, here are some general best practices:

  • Ensure the resource has curl installed (alternatively, wget or busybox)
  • Ensure the resource can curl your Coder access URL
  • Manually connect to the resource and check the agent logs (e.g., kubectl exec, docker exec or AWS console)
    • The Coder agent logs are typically stored in /tmp/coder-agent.log
    • The Coder agent startup script logs are typically stored in /tmp/coder-startup-script.log
    • The Coder agent shutdown script logs are typically stored in /tmp/coder-shutdown-script.log
  • This can also happen if the websockets are not being forwarded correctly when running Coder behind a reverse proxy. Read our reverse-proxy docs

Startup script issues

Depending on the contents of the startup script, and whether or not the startup script behavior is set to blocking or non-blocking, you may notice issues related to the startup script. In this section we will cover common scenarios and how to resolve them.

Unable to access workspace, startup script is still running

If you're trying to access your workspace and are unable to because the startup script is still running, it means the startup script behavior option is set to blocking or you have enabled the --wait=yes option (for e.g. coder ssh or coder config-ssh). In such an event, you can always access the workspace by using the web terminal, or via SSH using the --wait=no option. If the startup script is running longer than it should, or never completing, you can try to debug the startup script to resolve the issue. Alternatively, you can try to force the startup script to exit by terminating processes started by it or terminating the startup script itself (on Linux, ps and kill are useful tools).

For tips on how to write a startup script that doesn't run forever, see the startup_script section. For more ways to override the startup script behavior, see the startup_script_behavior section.

Template authors can also set the startup script behavior option to non-blocking, which will allow users to access the workspace while the startup script is still running. Note that the workspace must be updated after changing this option.

Your workspace may be incomplete

If you see a warning that your workspace may be incomplete, it means you should be aware that programs, files, or settings may be missing from your workspace. This can happen if the startup script is still running or has exited with a non-zero status (see startup script error). No action is necessary, but you may want to start a new shell session after it has completed or check the startup script logs to see if there are any issues.

Session was started before the startup script finished

The web terminal may show this message if it was started before the startup script finished, but the startup script has since finished. This message can safely be dismissed, however, be aware that your preferred shell or dotfiles may not yet be activated for this shell session. You can either start a new session or source your dotfiles manually. Note that starting a new session means that commands running in the terminal will be terminated and you may lose unsaved work.

Examples for activating your preferred shell or sourcing your dotfiles:

  • exec zsh -l
  • source ~/.bashrc

Startup script exited with an error

When the startup script exits with an error, it means the last command run by the script failed. When set -e is used, this means that any failing command will immediately exit the script and the remaining commands will not be executed. This also means that your workspace may be incomplete. If you see this error, you can check the startup script logs to figure out what the issue is.

Common causes for startup script errors:

  • A missing command or file
  • A command that fails due to missing permissions
  • Network issues (e.g., unable to reach a server)

Debugging the startup script

The simplest way to debug the startup script is to open the workspace in the Coder dashboard and select "Show startup log" (if not already visible). This will show all the output from the script. Another option is to view the log file inside the workspace (usually /tmp/coder-startup-script.log). If the logs don't indicate what's going on or going wrong, you can increase verbosity by adding set -x to the top of the startup script (note that this will show all commands run and may output sensitive information). Alternatively, you can add echo statements to show what's going on.

Here's a short example of an informative startup script:

echo "Running startup script..."
echo "Run: long-running-command"
/path/to/long-running-command
status=$?
echo "Done: long-running-command, exit status: ${status}"
if [ $status -ne 0 ]; then
  echo "Startup script failed, exiting..."
  exit $status
fi

Note

We don't use set -x here because we're manually echoing the commands. This protects against sensitive information being shown in the log.

This script tells us what command is being run and what the exit status is. If the exit status is non-zero, it means the command failed and we exit the script. Since we are manually checking the exit status here, we don't need set -e at the top of the script to exit on error.

Note

If you aren't seeing any logs, check that the dir directive points to a valid directory in the file system.

Slow workspace startup times

If your workspaces are taking longer to start than expected, or longer than desired, you can diagnose which steps have the highest impact in the workspace build timings UI (available in v2.17 and beyond). Admins can can programmatically pull startup times for individual workspace builds using our build timings API endpoint.

See our guide on optimizing workspace build times to optimize your templates based on this data.

Workspace build timings UI

Cannot connect to the Docker daemon

If a Docker-based template fails to provision with an error like Cannot connect to the Docker daemon at unix:///var/run/docker.sock, the Coder host cannot reach the Docker socket. Confirm that Docker is installed and running on the host. If you run Docker through rootless Docker, Colima, Podman, or a similar tool, the daemon may expose its socket at a non-default path, so set DOCKER_HOST to point at it. Refer to Cannot connect to the Docker daemon for the full steps.

Docker Workspaces on Raspberry Pi OS

Unable to query ContainerMemory

When you query ContainerMemory and encounter the error:

open /sys/fs/cgroup/memory.max: no such file or directory

This error mostly affects Raspberry Pi OS, but might also affect older Debian-based systems as well.

Add cgroup_memory and cgroup_enable to cmdline.txt:
  1. Confirm the list of existing cgroup controllers doesn't include memory:

    $ cat /sys/fs/cgroup/cgroup.controllers
    cpuset cpu io pids
    
    $ cat /sys/fs/cgroup/cgroup.subtree_control
    cpuset cpu io pids
    
  2. Add cgroup entries to cmdline.txt in /boot/firmware (or /boot/ on older Pi OS releases):

    cgroup_memory=1 cgroup_enable=memory
    

    You can use sed to add it to the file for you:

    sudo sed -i '$s/$/ cgroup_memory=1 cgroup_enable=memory/' /boot/firmware/cmdline.txt
    
  3. Reboot:

    sudo reboot
    
  4. Confirm that the list of cgroup controllers now includes memory:

    $ cat /sys/fs/cgroup/cgroup.controllers
    cpuset cpu io memory pids
    
    $ cat /sys/fs/cgroup/cgroup.subtree_control
    cpuset cpu io memory pids
    

Read more about cgroup controllers in The Linux Kernel documentation.