This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 2525023a567 Fix "Docker is not running" error guidance for GitHub
Codespaces (#62580)
2525023a567 is described below
commit 2525023a567165606a1b885aaf60445d876d6363
Author: Jarek Potiuk <[email protected]>
AuthorDate: Sat Feb 28 21:48:17 2026 +0100
Fix "Docker is not running" error guidance for GitHub Codespaces (#62580)
When running Breeze in a GitHub Codespace, the generic "Docker is not
running" error gave no Codespace-specific troubleshooting hints. This
change:
- Adds feature in devcontainers to enable docker-in-docker
- Shows Docker's stderr output when `docker info` fails (previously
suppressed) so users can see the actual error.
- Detects the CODESPACES environment variable and prints targeted
troubleshooting steps (check socket, permissions, rebuild container).
- Adds a Docker verification step to the beginner quick-start guide.
- Adds a troubleshooting section to the Codespaces setup guide.
Closes: #62405
Co-authored-by: Claude Opus 4.6 <[email protected]>
---
.devcontainer/devcontainer.json | 3 ++
.devcontainer/mysql/devcontainer.json | 3 ++
.devcontainer/postgres/devcontainer.json | 3 ++
.../03a_contributors_quick_start_beginners.rst | 16 ++++++++--
.../contributors_quick_start_codespaces.rst | 34 ++++++++++++++++++++++
.../airflow_breeze/utils/docker_command_utils.py | 14 ++++++++-
6 files changed, 69 insertions(+), 4 deletions(-)
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index f6f28ac2a12..86d5400c149 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -4,6 +4,9 @@
"../scripts/ci/docker-compose/devcontainer.yml",
"../scripts/ci/docker-compose/devcontainer-sqlite.yml"
],
+ "features": {
+ "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+ },
"settings": {
"terminal.integrated.defaultProfile.linux": "bash"
},
diff --git a/.devcontainer/mysql/devcontainer.json
b/.devcontainer/mysql/devcontainer.json
index 011ff292d27..ef1ef2de1f2 100644
--- a/.devcontainer/mysql/devcontainer.json
+++ b/.devcontainer/mysql/devcontainer.json
@@ -5,6 +5,9 @@
"../../scripts/ci/docker-compose/backend-mysql.yml",
"../../scripts/ci/docker-compose/devcontainer-mysql.yml"
],
+ "features": {
+ "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+ },
"settings": {
"terminal.integrated.defaultProfile.linux": "bash"
},
diff --git a/.devcontainer/postgres/devcontainer.json
b/.devcontainer/postgres/devcontainer.json
index 419dbedfa1d..1be456df375 100644
--- a/.devcontainer/postgres/devcontainer.json
+++ b/.devcontainer/postgres/devcontainer.json
@@ -5,6 +5,9 @@
"../../scripts/ci/docker-compose/backend-postgres.yml",
"../../scripts/ci/docker-compose/devcontainer-postgres.yml"
],
+ "features": {
+ "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+ },
"settings": {
"terminal.integrated.defaultProfile.linux": "bash"
},
diff --git a/contributing-docs/03a_contributors_quick_start_beginners.rst
b/contributing-docs/03a_contributors_quick_start_beginners.rst
index 0427a7c19c3..6a04887441e 100644
--- a/contributing-docs/03a_contributors_quick_start_beginners.rst
+++ b/contributing-docs/03a_contributors_quick_start_beginners.rst
@@ -148,7 +148,17 @@ Option B – One-Click GitHub Codespaces
chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version
-4. Install Breeze and start the development container
+4. Verify Docker is accessible
+
+.. code-block:: bash
+
+ docker info
+
+ If ``docker info`` fails, try rebuilding the Codespace container
+ (Command Palette → *Codespaces: Rebuild Container*) or restarting
+ the Codespace from the GitHub Codespaces dashboard.
+
+5. Install Breeze and start the development container
.. code-block:: bash
@@ -160,10 +170,10 @@ Option B – One-Click GitHub Codespaces
uv run dev/ide_setup/setup_vscode.py
breeze start-airflow
-5. Edit a file in the editor, save, and commit via the Source Control sidebar.
+6. Edit a file in the editor, save, and commit via the Source Control sidebar.
Push when prompted.
-6. Press **Create pull request** when GitHub offers.
+7. Press **Create pull request** when GitHub offers.
diff --git
a/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst
b/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst
index 447e6ba4637..cb2b984815d 100644
--- a/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst
+++ b/contributing-docs/quick-start-ide/contributors_quick_start_codespaces.rst
@@ -46,4 +46,38 @@ Setup and develop using GitHub Codespaces
as Codespaces use Visual Studio Code as interface.
+Troubleshooting Docker in Codespaces
+-------------------------------------
+
+If you see a "Docker is not running" error when running Breeze commands, try
these steps:
+
+1. Verify that Docker is accessible by running:
+
+ .. code-block:: bash
+
+ docker info
+
+2. If the command fails, check that the Docker socket exists:
+
+ .. code-block:: bash
+
+ ls -la /var/run/docker.sock
+
+3. Check that your user has permission to access Docker:
+
+ .. code-block:: bash
+
+ groups $USER
+
+ You should see ``docker`` in the list. If not, add yourself to the group:
+
+ .. code-block:: bash
+
+ sudo usermod -aG docker $USER
+
+4. If the above steps do not help, rebuild the devcontainer
+ (Command Palette → *Codespaces: Rebuild Container*) or restart the Codespace
+ from the GitHub Codespaces dashboard.
+
+
Follow the `Quick start
<../03b_contributors_quick_start_seasoned_developers.rst>`_ for typical
development tasks.
diff --git a/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py
b/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py
index 13413108869..fef8b8d597a 100644
--- a/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py
+++ b/dev/breeze/src/airflow_breeze/utils/docker_command_utils.py
@@ -175,7 +175,7 @@ def check_docker_is_running():
response = run_command(
["docker", "info"],
no_output_dump_on_exception=True,
- text=False,
+ text=True,
capture_output=True,
check=False,
)
@@ -183,6 +183,18 @@ def check_docker_is_running():
get_console().print(
"[error]Docker is not running.[/]\n[warning]Please make sure
Docker is installed and running.[/]"
)
+ if response.stderr:
+ get_console().print(f"\n[warning]Docker error
output:[/]\n{response.stderr.strip()}")
+ if os.environ.get("CODESPACES", "").lower() == "true":
+ get_console().print(
+ "\n[info]It looks like you are running in a GitHub
Codespace.[/]\n"
+ "[info]Try the following troubleshooting steps:[/]\n"
+ " 1. Check if the Docker socket exists: ls -la
/var/run/docker.sock\n"
+ " 2. Check Docker socket permissions: groups $USER\n"
+ " 3. Try restarting the Codespace from the GitHub Codespaces
dashboard\n"
+ " 4. If the issue persists, rebuild the devcontainer "
+ "(Command Palette -> 'Codespaces: Rebuild Container')\n"
+ )
sys.exit(1)
