@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/runner-environment/service-container-no-healthcheck.yml

@@ -0,0 +1,158 @@
+id: runner-environment-066
+title: "Service Container Unhealthy — No Healthcheck Causes Job to Run Before Container Is Ready"
+category: runner-environment
+severity: error
+tags:
+  - service-container
+  - postgres
+  - mysql
+  - redis
+  - healthcheck
+  - docker
+  - connection-refused
+patterns:
+  - regex: "db service is unhealthy"
+    flags: "i"
+  - regex: "(?:postgres|mysql|redis|service).*(?:unhealthy|not ready|failed to start)"
+    flags: "i"
+  - regex: "One or more containers failed to start"
+    flags: "i"
+  - regex: "Connection refused.*(?:5432|3306|6379)"
+    flags: "i"
+  - regex: "could not connect to server.*Connection refused"
+    flags: "i"
+  - regex: "ECONNREFUSED.*(?:5432|3306|6379)"
+    flags: "i"
+error_messages:
+  - "Failed to initialize, db service is unhealthy."
+  - "One or more containers failed to start."
+  - "Error: connect ECONNREFUSED 127.0.0.1:5432"
+  - "could not connect to server: Connection refused"
+  - "Is the server running on that host and accepting TCP/IP connections on port 5432?"
+  - "ERROR 2002 (HY000): Can't connect to MySQL server on '127.0.0.1' (111)"
+root_cause: |
+  GitHub Actions starts service containers (defined under `services:`) before
+  job steps begin, but it does NOT wait for the container's internal process to
+  be fully ready unless a healthcheck is configured. The runner only waits for
+  the container to be in a running state — not for the database or service
+  inside to accept connections.
+
+  Databases like PostgreSQL, MySQL, and Redis typically take several seconds
+  after the container starts before they are ready to accept connections. Without
+  a healthcheck configured via the `options:` key, GitHub Actions proceeds to
+  run job steps immediately while the service is still initializing. The first
+  step that attempts a database connection will fail with "Connection refused"
+  or "service is unhealthy."
+
+  Common misconfiguration patterns:
+  1. No `options:` block at all — the service starts but the job doesn't wait
+     for readiness. The runner polls the healthcheck status if one is present.
+  2. Wrong healthcheck command — using `pg_isready` without the correct user/host
+     flags, or using `mysqladmin ping` without the correct credentials.
+  3. Insufficient retries/timeouts — using `--health-retries 1` means a single
+     failed attempt marks the container unhealthy immediately.
+  4. Port not mapped — the `ports:` key is optional when running steps directly
+     on the runner (accessing via 127.0.0.1), but is required when steps run
+     inside a container.
+
+  Note: Even with a healthcheck, the DB container can transiently fail the
+  healthcheck during slow GH-hosted runner provisioning. Default values of
+  `--health-interval 10s --health-timeout 5s --health-retries 5` work for
+  most cases, but MySQL/MariaDB may need longer retries during first initialization.
+fix: |
+  Add a `options:` block to your service definition with a proper Docker
+  healthcheck command. GitHub Actions reads the container's healthcheck status
+  and waits until the container reports "healthy" before starting job steps.
+
+  PostgreSQL:
+    Use `pg_isready` with `-h localhost` and the correct username.
+
+  MySQL/MariaDB:
+    Use `mysqladmin ping` with credentials matching the MYSQL_ROOT_PASSWORD.
+
+  Redis:
+    Use `redis-cli ping` — returns PONG when Redis is ready.
+
+  If the container is still failing, increase `--health-retries` and
+  `--health-start-period` to give the container more initialization time.
+  MySQL in particular needs a longer start period on its first run because it
+  initializes the data directory.
+fix_code:
+  - language: yaml
+    label: "PostgreSQL service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_USER: testuser
+                POSTGRES_PASSWORD: testpass
+                POSTGRES_DB: testdb
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+              env:
+                DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb
+  - language: yaml
+    label: "MySQL service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            mysql:
+              image: mysql:8.0
+              env:
+                MYSQL_ROOT_PASSWORD: rootpass
+                MYSQL_DATABASE: testdb
+              ports:
+                - 3306:3306
+              options: >-
+                --health-cmd "mysqladmin ping -h 127.0.0.1 -u root -prootpass"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 10
+                --health-start-period 30s
+  - language: yaml
+    label: "Redis service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            redis:
+              image: redis:7
+              ports:
+                - 6379:6379
+              options: >-
+                --health-cmd "redis-cli ping"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+prevention:
+  - "Always add a `options: --health-cmd ...` block to every service container — the runner will wait for 'healthy' status before running steps."
+  - "Use `--health-start-period 30s` for MySQL/MariaDB which initializes its data directory on the first run and takes longer than PostgreSQL or Redis."
+  - "Test your healthcheck command locally with `docker run --health-cmd ...` to verify it exits 0 when the service is ready."
+  - "Use `ports: - 5432:5432` when steps run directly on the runner host (ubuntu-latest); ports are optional when steps run in a container job."
+  - "Avoid hardcoded `sleep 30` workarounds — these waste time on fast machines and still fail on slow ones. Use healthchecks instead."
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/creating-postgresql-service-containers"
+    label: "GitHub Docs: Creating PostgreSQL service containers"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/creating-redis-service-containers"
+    label: "GitHub Docs: Creating Redis service containers"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container"
+    label: "GitHub Docs: Running jobs in a container (services section)"
+  - url: "https://stackoverflow.com/questions/60618118/docker-postgres-image-failed-to-initialize-db-service-is-unhealthy"
+    label: "Stack Overflow #60618118: db service is unhealthy (25 votes, 8.8K views)"
+  - url: "https://github.com/orgs/community/discussions/27021"
+    label: "GitHub Community #27021: MySQL service never comes up healthy"

package/errors/runner-environment/setup-node-v5-corepack-pnpm-not-found.yml

@@ -0,0 +1,101 @@
+id: runner-environment-060
+title: "setup-node@v5 Cannot Locate pnpm After Corepack Enable"
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - pnpm
+  - corepack
+  - v5
+  - package-manager
+patterns:
+  - regex: "Unable to locate executable file: pnpm"
+    flags: "i"
+  - regex: "actions/setup-node@[a-z0-9]+ # v5"
+    flags: "i"
+  - regex: "package-manager-cache: true"
+    flags: "i"
+error_messages:
+  - "Error: Unable to locate executable file: pnpm. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable."
+root_cause: |
+  `actions/setup-node@v5` changed how corepack and package manager shims are
+  initialized compared to v4. In v5, the action enables `package-manager-cache: true`
+  by default and reads the `packageManager` field from `package.json` to configure
+  corepack, but it no longer automatically activates corepack shims for the pnpm
+  binary in the runner's PATH.
+
+  In v4, setup-node would run `corepack enable` implicitly as part of its package
+  manager setup, making pnpm available immediately after the action. In v5 this
+  behavior changed: corepack is configured for caching purposes but pnpm shims are
+  not written into PATH, so any subsequent `corepack enable` or direct `pnpm`
+  invocation fails with "Unable to locate executable file: pnpm."
+
+  The issue is specific to v5 because the internal action scripts now use Node 24
+  and a refactored corepack integration path that treats corepack enablement as
+  separate from the shim installation step.
+
+  Downgrading to `actions/setup-node@v4` restores the previous behavior where pnpm
+  shims are automatically available after the action.
+fix: |
+  Use `pnpm/action-setup` BEFORE `actions/setup-node` to install pnpm independently
+  of corepack shim management. This is the officially recommended pattern for pnpm
+  on GitHub-hosted runners and works correctly with both v4 and v5 of setup-node.
+
+  Alternatively, pin to `actions/setup-node@v4` until setup-node@v5 resolves the
+  corepack shim regression.
+
+  Do NOT rely on `corepack enable` run after setup-node@v5 to make pnpm available —
+  the shim is not written even after corepack is enabled in a subsequent step.
+fix_code:
+  - language: yaml
+    label: "Wrong: setup-node@v5 + corepack enable (pnpm not found)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v5   # v5 does not write pnpm shim
+          with:
+            node-version-file: package.json
+        - run: |
+            corepack enable             # pnpm still not in PATH after this
+            corepack prepare --activate
+        - run: pnpm install             # Error: Unable to locate executable file: pnpm
+  - language: yaml
+    label: "Correct: pnpm/action-setup before setup-node (works with v4 and v5)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: pnpm/action-setup@v4    # install pnpm FIRST, independent of corepack
+          with:
+            version: 10
+        - uses: actions/setup-node@v5
+          with:
+            node-version-file: package.json
+            cache: pnpm
+        - run: pnpm install --frozen-lockfile
+  - language: yaml
+    label: "Alternative: pin to setup-node@v4 (restores previous corepack behavior)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4   # v4 writes corepack shims automatically
+          with:
+            node-version-file: package.json
+        - run: |
+            corepack enable
+            corepack prepare --activate
+        - run: pnpm install --frozen-lockfile
+prevention:
+  - "Use pnpm/action-setup before setup-node for reliable pnpm availability regardless of setup-node version."
+  - "Do not assume corepack shim behavior is identical between setup-node major versions."
+  - "Pin action versions with SHAs (e.g. @a0853c24...) to avoid unexpected behavior changes on major bumps."
+  - "Read setup-node release notes and CHANGELOG when upgrading from v4 to v5 — corepack integration changed."
+  - "Test pnpm availability explicitly in CI by adding a debug step: run: which pnpm && pnpm --version"
+docs:
+  - url: "https://github.com/actions/setup-node/issues/1357"
+    label: "actions/setup-node#1357: v5 fails immediately when using pnpm (31 reactions)"
+  - url: "https://github.com/pnpm/action-setup"
+    label: "pnpm/action-setup: Official pnpm GitHub Action"
+  - url: "https://nodejs.org/api/corepack.html"
+    label: "Node.js Corepack documentation"
+  - url: "https://github.com/actions/setup-node/releases"
+    label: "actions/setup-node releases and CHANGELOG"

package/errors/runner-environment/setup-node-yarn-not-installed-self-hosted.yml

@@ -0,0 +1,76 @@
+id: runner-environment-074
+title: "setup-node Does Not Install Yarn on Self-Hosted Runners"
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - yarn
+  - self-hosted-runner
+  - package-manager
+  - corepack
+patterns:
+  - regex: "yarn.*command not found|command not found.*yarn"
+    flags: "i"
+  - regex: "yarn: not found|sh.*yarn.*127"
+    flags: "i"
+error_messages:
+  - "yarn: command not found"
+  - "/bin/sh: 1: yarn: not found"
+  - "Process completed with exit code 127"
+root_cause: |
+  `actions/setup-node` does NOT install Yarn on self-hosted runners. On GitHub-hosted runners,
+  Yarn is pre-installed as part of the runner image (included in ubuntu-22.04, ubuntu-24.04,
+  macOS, and Windows hosted images). When migrating to self-hosted runners, workflows that call
+  `yarn install` fail with `yarn: command not found` (exit code 127) because the binary is absent.
+
+  The action provides `cache: 'yarn'` to restore cached modules and registry URL configuration,
+  but does NOT bootstrap the Yarn binary itself. As of Node.js 16+, Yarn v2+ (Berry) is distributed
+  via Corepack, but Corepack shims are disabled by default in Node.js — setup-node@v4 requires
+  explicit `enable-corepack: true` to activate them.
+
+  159 reactions on actions/setup-node#182 (open since Dec 2021).
+fix: |
+  Option A (Yarn v1): Install Yarn explicitly via npm in a dedicated step before using it.
+  Option B (Yarn v2/v3/v4 Berry): Enable Corepack via setup-node's `enable-corepack: true`
+  input together with a `packageManager` field in package.json specifying the exact Yarn version.
+  Option C: Use `volta-cli/action` or a custom self-hosted runner image with Yarn pre-installed.
+fix_code:
+  - language: yaml
+    label: "Option A: install Yarn v1 explicitly (compatible with all self-hosted runners)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            cache: 'yarn'
+        - name: Install Yarn
+          run: npm install -g yarn@1
+        - name: Install dependencies
+          run: yarn install --frozen-lockfile
+
+  - language: yaml
+    label: "Option B: enable Corepack for Yarn v2+ (requires packageManager in package.json)"
+    code: |
+      # Requires package.json to include: "packageManager": "yarn@4.x.x"
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            enable-corepack: true   # activates Corepack shims including the yarn binary
+            cache: 'yarn'
+        - name: Install dependencies
+          run: yarn install --immutable
+prevention:
+  - "On self-hosted runners, never assume GitHub-hosted image tools are pre-installed — audit all tool dependencies."
+  - "Explicitly install or activate package managers (yarn, pnpm, bun) in workflow setup steps."
+  - "Use enable-corepack: true in setup-node@v4 for Yarn v2+ projects with packageManager in package.json."
+  - "Consider maintaining a custom self-hosted runner image with required package managers pre-installed."
+docs:
+  - url: "https://github.com/actions/setup-node/issues/182"
+    label: "actions/setup-node #182 — Yarn not installed on self-hosted runners (159 reactions)"
+  - url: "https://github.com/actions/setup-node#corepack"
+    label: "setup-node — Corepack support documentation"
+  - url: "https://yarnpkg.com/corepack"
+    label: "Yarn — Corepack installation guide"

package/errors/runner-environment/setup-python-externally-managed-env-error.yml

@@ -0,0 +1,95 @@
+id: "runner-environment-073"
+title: "pip install fails with externally-managed-environment on Ubuntu 22.04/24.04"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "python"
+  - "pip"
+  - "ubuntu-2204"
+  - "ubuntu-2404"
+  - "pep668"
+  - "virtualenv"
+patterns:
+  - regex: "error: externally-managed-environment"
+    flags: "i"
+  - regex: "This environment is externally managed"
+    flags: "i"
+  - regex: "To install Python packages system-wide, try apt-get install"
+    flags: "i"
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "╰─> To install Python packages system-wide, try apt-get install python3-xyz"
+  - "hint: See PEP 668 for the detailed specification of this behavior."
+root_cause: |
+  PEP 668 (adopted in Python 3.11) marks system-managed Python installations as
+  "externally managed" to prevent pip from overwriting OS package manager state.
+  Ubuntu 22.04 and 24.04 runner images ship with a system Python 3.10/3.12 that
+  carries this marker, and newer versions of pip (>=22.3) enforce it.
+
+  Workflows that run bare `pip install` or `pip install -r requirements.txt` against
+  the system interpreter fail with this error. The issue did not exist on ubuntu-20.04
+  (Python 3.8) and began appearing when teams migrated to ubuntu-22.04 or ubuntu-latest
+  (which moved to ubuntu-24.04 in May 2025).
+
+  Even when setup-python is used, if the step that runs pip install activates the wrong
+  interpreter (e.g., the system Python instead of the toolcache one), the same error
+  occurs. This often happens when shell scripts or Makefiles call `python3` directly.
+fix: |
+  Option 1 (preferred): Use a virtual environment so pip installs into an isolated,
+  non-system directory that is not subject to the externally-managed restriction.
+
+  Option 2: Pin setup-python@v5 to your required version; its toolcache interpreter
+  is not marked as externally managed and accepts pip installs freely.
+
+  Option 3 (quick fix, not recommended for production): Pass --break-system-packages.
+fix_code:
+  - language: yaml
+    label: "Use a virtual environment (recommended)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Create virtualenv and install
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate  # Linux/macOS
+          # .venv\Scripts\activate   # Windows
+          pip install -r requirements.txt
+
+      - name: Run with virtualenv active
+        run: |
+          source .venv/bin/activate
+          pytest
+
+  - language: yaml
+    label: "Use setup-python toolcache interpreter (pip installs without restriction)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt   # uses toolcache Python, not system Python
+
+  - language: yaml
+    label: "Quick fix: --break-system-packages (not recommended)"
+    code: |
+      - name: Install dependencies
+        run: pip install --break-system-packages -r requirements.txt
+prevention:
+  - "Always activate setup-python before any pip install call to use the toolcache interpreter instead of system Python."
+  - "Use virtual environments in CI workflows, especially when migrating from ubuntu-20.04 to 22.04/24.04."
+  - "Audit Makefiles and shell scripts that call 'python3' directly — they may bypass setup-python's PATH manipulation."
+  - "Run your workflow on ubuntu-22.04 or ubuntu-24.04 in a test branch before migrating from ubuntu-20.04."
+docs:
+  - url: "https://peps.python.org/pep-0668/"
+    label: "PEP 668 — Marking Python base environments as externally managed"
+  - url: "https://github.com/actions/setup-python/issues/1280"
+    label: "actions/setup-python#1280 — externally-managed-environment discussion"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software"
+    label: "GitHub Docs — Supported software on GitHub-hosted runners"
+  - url: "https://github.com/actions/runner-images/issues/11101"
+    label: "runner-images#11101 — Ubuntu 20.04 retirement tracking issue"

package/errors/runner-environment/windows-2019-runner-retired-june2025.yml

@@ -0,0 +1,118 @@
+id: runner-environment-065
+title: "Windows 2019 Runner Retired — Jobs Fail After June 30, 2025"
+category: runner-environment
+severity: error
+tags:
+  - windows-2019
+  - runner-retirement
+  - deprecated
+  - windows
+  - runner-label
+  - brownout
+patterns:
+  - regex: "windows-2019.*no longer supported"
+    flags: "i"
+  - regex: "runs-on.*windows-2019.*deprecated"
+    flags: "i"
+  - regex: "The windows-2019 runner image is no longer supported"
+    flags: "i"
+  - regex: "Error.*windows-2019.*not available"
+    flags: "i"
+error_messages:
+  - "Error: The windows-2019 runner image is no longer supported. Migrate to windows-2022 or windows-2025."
+  - "##[error]Job failed: The runner image 'windows-2019' is deprecated and no longer supported."
+  - "Windows Server 2019 is no longer supported as a GitHub Actions runner image."
+root_cause: |
+  The `windows-2019` runner image was retired by GitHub Actions on June 30, 2025
+  (runner-images#12045). Deprecation brownouts began June 1, 2025, during which
+  jobs using `windows-2019` would temporarily fail during scheduled brownout
+  windows (June 3, 10, 17, 24 — 13:00–21:00 UTC). After June 30, 2025, the
+  image was fully unsupported and jobs using `runs-on: windows-2019` fail
+  immediately with no runner available.
+
+  Windows Server 2019 reached End of Mainstream Support from Microsoft on
+  January 9, 2024, making it untenable as a CI runner image for security
+  and support reasons.
+
+  Key differences that may require migration work:
+  - Windows 2022 and 2025 use Visual Studio 2022 and VS 2026 respectively
+    (windows-2019 had Visual Studio 2019). MSBuild project compatibility,
+    compiler toolset versions, and SDK paths differ.
+  - Some pre-installed tools (e.g., specific .NET Framework versions, MSVC
+    compiler toolsets, legacy SDK components) were present on windows-2019
+    but not on windows-2022 or windows-2025.
+  - Windows Server 2025 images include Windows PowerShell 5.1 and
+    PowerShell 7.x; path behaviors for Windows-specific paths may differ.
+fix: |
+  Migrate runs-on: windows-2019 to runs-on: windows-2022 or windows-2025:
+
+  1. **windows-2022** (recommended for most teams): Includes VS 2022,
+     .NET 6/7/8 LTS, and the same tool catalog as windows-2019 minus
+     legacy VS 2019 components. Most projects migrate with no changes.
+
+  2. **windows-2025** (latest, includes VS 2026): Best for projects
+     requiring the latest MSVC toolchain, Windows 11 APIs, or ARM64
+     development. Note that windows-latest now points to this image.
+
+  3. **Check MSBuild ToolsVersion**: If your project uses MSBuild with
+     explicit ToolsVersion="15.0" or "16.0" references, update to
+     ToolsVersion="Current" or leave it unspecified to use the
+     installed version.
+
+  4. **Verify .NET SDK availability**: Confirm the .NET SDK version your
+     project needs is available on the target image by checking the
+     published software inventory for windows-2022 or windows-2025.
+fix_code:
+  - language: yaml
+    label: "Migrate from windows-2019 to windows-2022"
+    code: |
+      jobs:
+        build:
+          # windows-2019 is RETIRED as of June 30, 2025
+          # runs-on: windows-2019  ← no longer supported
+          runs-on: windows-2022     # VS 2022, .NET 8 LTS pre-installed
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyProject.sln /p:Configuration=Release
+  - language: yaml
+    label: "Migrate to windows-2025 with VS 2026 (latest)"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2025    # Windows Server 2025, VS 2026
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup .NET
+              uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '8.x'
+            - name: Build
+              run: dotnet build --configuration Release
+  - language: yaml
+    label: "Matrix to test windows-2022 and windows-2025 before committing"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [windows-2022, windows-2025]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: msbuild MyProject.sln
+prevention:
+  - "Avoid pinning to specific OS-versioned runner labels (windows-2019, ubuntu-20.04) in long-lived workflows — add a review calendar reminder every 12 months to check for upcoming deprecations."
+  - "Subscribe to GitHub notifications for the actions/runner-images repository to receive deprecation announcements months before retirement."
+  - "Use `windows-latest` for flexibility where VS version compatibility isn't critical — it automatically tracks the current supported image."
+  - "After migrating, run the full test suite and check compiler/toolchain version outputs in CI to catch any implicit behavior differences."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12045"
+    label: "runner-images #12045: Windows 2019 deprecation announcement (June 2025)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md"
+    label: "Windows Server 2022 runner software inventory"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 runner software inventory"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs: About GitHub-hosted runners — available images"

package/errors/runner-environment/windows-2022-docker-daemon-not-started.yml

@@ -0,0 +1,108 @@
+id: runner-environment-069
+title: "Windows 2022 Runner Docker Engine Named Pipe Not Found on Start"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - docker
+  - runner-image
+  - intermittent
+  - named-pipe
+patterns:
+  - regex: "failed to connect to the docker API at npipe:////\\.?/pipe/docker_engine"
+    flags: "i"
+  - regex: "open //\\.?/pipe/docker_engine.*The system cannot find the file specified"
+    flags: "i"
+  - regex: "error during connect.*pipe/docker_engine.*daemon running"
+    flags: "i"
+  - regex: "Docker Engine.*Stopped|docker.*service.*not running"
+    flags: "i"
+error_messages:
+  - "failed to connect to the docker API at npipe:////./pipe/docker_engine; check if the path is correct and if the daemon is running: open //./pipe/docker_engine: The system cannot find the file specified."
+  - "error during connect: Get \"http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.45/info\": open //./pipe/docker_engine: The system cannot find the file specified."
+root_cause: |
+  On GitHub-hosted `windows-2022` runners, the Docker Engine service occasionally
+  fails to start before the workflow job begins. The Docker Engine runs as a Windows
+  service (`docker`) and the runner sometimes starts executing job steps before the
+  service has fully initialized and opened its named pipe at `//./pipe/docker_engine`.
+
+  This is an intermittent race condition between the runner agent startup and the
+  Docker Engine service startup sequence. The issue was reported in February 2026
+  (runner-images#13729) and confirmed to affect `windows-2022` at ~50% frequency
+  for some users. The `windows-2025` image is less affected.
+
+  The Docker Engine service shows `Status: Stopped` when queried immediately after
+  the runner starts. Manually starting the service (via `Start-Service docker`)
+  resolves the issue for that run. Job reruns also frequently succeed because they
+  land on a fresh host with Docker already running.
+fix: |
+  Add a step early in your job to verify Docker is running and start it if not:
+
+  ```yaml
+  - name: Ensure Docker Engine is running
+    shell: pwsh
+    run: |
+      $service = Get-Service -Name docker -ErrorAction SilentlyContinue
+      if ($service.Status -ne 'Running') {
+        Start-Service docker
+        $timeout = 60
+        $elapsed = 0
+        while ((Get-Service docker).Status -ne 'Running' -and $elapsed -lt $timeout) {
+          Start-Sleep -Seconds 2
+          $elapsed += 2
+        }
+      }
+      docker info
+  ```
+
+  If the issue is sporadic, a simpler retry on job failure may suffice. You can
+  also switch to `windows-2025` which has a lower incidence of this race condition.
+fix_code:
+  - language: yaml
+    label: "Guard step — ensure Docker service is running before use"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Ensure Docker Engine is running
+              shell: pwsh
+              run: |
+                $svc = Get-Service docker -ErrorAction SilentlyContinue
+                if ($null -eq $svc -or $svc.Status -ne 'Running') {
+                  Write-Host "Docker service not running — starting..."
+                  Start-Service docker
+                  $deadline = (Get-Date).AddSeconds(60)
+                  while ((Get-Service docker).Status -ne 'Running') {
+                    if ((Get-Date) -gt $deadline) { throw "Docker failed to start in 60s" }
+                    Start-Sleep -Seconds 2
+                  }
+                  Write-Host "Docker service started."
+                }
+                docker info
+
+            - name: Build Docker image
+              run: docker build -t myimage .
+  - language: yaml
+    label: "Alternative — switch to windows-2025 (less affected)"
+    code: |
+      jobs:
+        build:
+          # windows-2025 has a lower frequency of this race condition
+          runs-on: windows-2025
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build Docker image
+              run: docker build -t myimage .
+prevention:
+  - "Add a Docker health-check step before any `docker` commands on Windows runners."
+  - "Consider using `windows-2025` which has fewer reports of this race condition."
+  - "Enable job reruns — this race condition is intermittent and reruns usually succeed."
+  - "Subscribe to runner-images announcements; GitHub is tracking this as a runner startup issue."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13729"
+    label: "GitHub Issue: windows-2022 docker not available when runner starts"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "About GitHub-hosted runners"