Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 39 additions & 3 deletions docs/templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -375,25 +375,61 @@ customize them however you like.
## Troubleshooting templates

Occasionally, you may run into scenarios where a workspace is created, but the
agent is not connected. This means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
agent is either not connected or the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
has failed or timed out.

### Agent connection issues

If the agent is not connected, it means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
has failed on the resource.

```console
$ coder ssh myworkspace
Waiting for [agent] to connect...
⢄⡱ Waiting for connection from [agent]...
```

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

- Ensure the resource has `curl` installed
- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
- Ensure the resource can `curl` your Coder [access
URL](./admin/configure.md#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`

### Agent does not become ready

If the agent does not become ready, it means the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status. This also means the [login before ready](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#login_before_ready) option hasn't been set to true.

```console
$ coder ssh myworkspace
⢄⡱ Waiting for [agent] to become ready...
```

To troubleshoot readiness issues, check the agent logs as suggested above. You can connect to the workspace using `coder ssh` with the `--no-wait` flag. Please note that while this makes login possible, the workspace may be in an incomplete state.

```console
$ coder ssh myworkspace --no-wait

> The workspace is taking longer than expected to get
ready, the agent startup script is still executing.
See troubleshooting instructions at: [...]

user@myworkspace $
```

If the startup script is expected to take a long time, you can try raising the timeout defined in the template:

```tf
resource "coder_agent" "main" {
# ...
login_before_ready = false
startup_script_timeout = 1800 # 30 minutes in seconds.
}
```

## Template permissions (enterprise)

Template permissions can be used to give users and groups access to specific
Expand Down