troubleshooting-dev-containers

EdwardAngert · EdwardAngert · commit 41167683ef17 · 2025-07-16T20:36:20.000Z
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -32,7 +32,7 @@ When a workspace with the dev containers integration starts:
 
 ## Features
 
-### Detection & Lifecycle
+### Detection and Lifecycle
 
 - Automatic dev container detection from repositories.
 - Change detection with rebuild prompts.
diff --git a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md
@@ -1,6 +1,9 @@
 # Troubleshooting dev containers
 
-## Dev Container Not Starting
+If you encounter issues with dev containers in your workspace, review the steps here as well as the dev containers
+[user](./index.md) and [admin](../../admin/templates/extending-templates/devcontainers.md#troubleshoot-common-issues) documentation.
+
+## Container does not start
 
 If your dev container fails to start:
 
@@ -13,4 +16,12 @@ If your dev container fails to start:
 1. Verify that Docker is running in your workspace.
 1. Ensure the `devcontainer.json` file is valid.
 1. Check that the repository has been cloned correctly.
-1. Verify the resource limits in your workspace are sufficient.
+1. Ensure the workspace image has Node/npm and the `devcontainers-cli` module installed.
+1. Verify that the resource limits in your workspace are sufficient.
+
+## Known Limitations
+
+Currently, dev containers are not compatible with the
+[prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md).
+
+If your template allows for prebuilt workspaces, do not select a prebuilt workspace if you plan to use a dev container.
