From 8a0311d4bc2ce366fa4e3f33b7618aa39f4015c7 Mon Sep 17 00:00:00 2001 From: Keiven Chang Date: Mon, 23 Feb 2026 22:49:35 +0000 Subject: [PATCH] docs: clarify Docker 29.x Dev Containers hang root cause and fix Rewrite the Docker version compatibility section to explain the actual root cause (docker events JSON field renamed from "status" to "Action" in Docker 29.x), specify affected/fixed extension versions, and list confirmed working combinations. Signed-off-by: Keiven Chang Co-authored-by: Cursor --- .devcontainer/README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/.devcontainer/README.md b/.devcontainer/README.md index a593f7646899..fcbc4f442e96 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -11,15 +11,17 @@ SPDX-License-Identifier: Apache-2.0 ### Docker Version Compatibility -**Docker 29.x has compatibility issues with Dev Containers (by Anysphere):** -- It is known that Docker Engine version **29.0.1** (released November 14, 2025) may cause Dev Containers to hang all the time, rendering it unusable -- The Dev Containers extension (v1.0.26) and devcontainer CLI (v0.75.0) were not tested against Docker 29.x -- Symptoms: Container builds successfully but connection hangs, requiring a manual reload to connect -- This may be fixed in a later version of the Anysphere Dev Containers extension and/or Docker Engine patch - -**Recommended Docker Version:** -- Use Docker Engine **28.5.2** or earlier for stable Dev Container operation -- Docker 27.x and 28.x series are confirmed working with current Dev Containers tooling +**Docker 29.x had a known incompatibility with Dev Containers extension at and before v1.0.26 (CLI v0.75.0):** + +- **Symptom:** Container builds and starts successfully (prints "Container started"), but the IDE hangs indefinitely and never connects. The `postCreateCommand` never runs. +- **Root cause:** The bundled devcontainers CLI spawns `docker events --format {{json .}} --filter event=start` to detect when a container starts. It checks `i.status || i.Status` in the parsed JSON. However, Docker 29.x emits the event type under the field name `"Action"` (e.g., `{"Action":"start",...}`), not `"status"`. The start event is received but silently discarded because the field name doesn't match, so the CLI waits forever. +- **Affected:** Docker Engine 29.0.0+ with Dev Containers extension v1.0.26 (CLI v0.75.0) +- **Fixed in:** Dev Containers extension **v1.0.32+** +- **Confirmed working combinations:** + - Docker 27.x / 28.x with any extension version + - Docker 29.x with Dev Containers extension v1.0.32+ + +**Recommended fix:** If you are using Docker 29.x, update the Dev Containers extension to **v1.0.32 or later**. Docker Engine 28.5.2 or earlier have been stable with all extension versions. ## Framework-Specific Devcontainers