@htekdev/actions-debugger 1.0.7 → 1.0.8

package/errors/runner-environment/docker-29-compose-v2-40-breaking.yml

@@ -0,0 +1,144 @@
+id: runner-environment-031
+title: "Docker 29.1 + Compose 2.40.3 Runner Update Breaks Compose Commands"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-compose
+  - docker-29
+  - compose-v2
+  - ubuntu
+  - windows
+  - runner-image-update
+patterns:
+  - regex: "docker compose.*unknown flag|unknown flag.*docker compose"
+    flags: "i"
+  - regex: "docker-compose.*command not found|docker-compose.*deprecated"
+    flags: "i"
+  - regex: "compose.*unknown command|error.*compose.*not a docker command"
+    flags: "i"
+  - regex: "docker compose.*plugin.*not found|failed to get plugins"
+    flags: "i"
+error_messages:
+  - "docker-compose: command not found"
+  - "unknown flag: --compatibility"
+  - "unknown shorthand flag: 'f' in -f"
+  - "Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.25"
+  - "'docker compose' requires at least 1 argument"
+root_cause: |
+  On **February 9, 2026**, GitHub pushed an update to Ubuntu and Windows runner images
+  that bumped Docker Server and Client from 28.x to **29.1.*** and Docker Compose from
+  2.x to **2.40.3** (announced in actions/runner-images#13474).
+
+  For Ubuntu 24.04, the update was **rolled back** on February 20, 2026 due to multiple
+  reported issues (#13682, #13691, #13684) and is being re-evaluated (tracked in
+  #14105). The Windows runner update proceeded.
+
+  **Breaking changes in Docker Compose 2.40.x and Docker 29.x:**
+
+  1. **`docker-compose` v1 binary removed** — Many older workflows use the hyphenated
+     `docker-compose` command (Compose v1). As of Docker Compose v2, only the plugin
+     form `docker compose` (no hyphen) is installed. Workflows with
+     `run: docker-compose up -d` fail with `command not found`.
+
+  2. **`--compatibility` flag removed** — The `docker compose --compatibility` flag
+     (for mapping v2 configs to v2-compatible behavior) was removed in 2.40.x.
+     Workflows that use `docker compose --compatibility up` fail.
+
+  3. **API version minimums** — Docker 29 raises the minimum supported Docker daemon
+     API version, breaking some older base images in service containers that use the
+     Docker socket with old clients.
+
+  4. **`COMPOSE_DOCKER_CLI_BUILD` env var deprecated** — Setting
+     `COMPOSE_DOCKER_CLI_BUILD=1` no longer has any effect; BuildKit is always used.
+
+  5. **Docker 29.5 `CLONE_NEWTIME` private time namespaces** — Docker 29.5 (released
+     May 2026) enables private time namespaces by default on kernels ≥ 5.6, which
+     breaks Docker-socket-passthrough patterns used in Cloud Native Buildpacks (CNB)
+     lifecycle builds. Buildpack builds via `pack build` or Spring Boot's built-in
+     Buildpacks fail silently or with lifecycle container errors.
+fix: |
+  **For `docker-compose` → `docker compose` migration:**
+  Replace all `docker-compose` (hyphenated) invocations with `docker compose` (space).
+  This is the most common fix.
+
+  **For `--compatibility` flag removal:**
+  Remove the `--compatibility` flag. Docker Compose v2 handles modern compose file
+  formats natively without this flag.
+
+  **For CNB/Buildpack Docker socket passthrough (Docker 29.5+):**
+  Mount the Docker socket without private time namespaces by using
+  `--security-opt=no-new-privileges:false` or by setting
+  `DOCKER_HOST` to use a sidecar daemon.
+
+  **For pinning Docker version on self-hosted runners:**
+  Pin to Docker 28.x until your Compose files and build pipelines are validated against
+  29.x.
+fix_code:
+  - language: yaml
+    label: "Replace docker-compose (v1) with docker compose (v2 plugin)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Old (docker-compose v1 — removed)
+            # - run: docker-compose up -d
+            # - run: docker-compose --compatibility up -d
+
+            # ✅ New (docker compose v2 plugin)
+            - name: Start services
+              run: docker compose up -d
+
+            - name: Run tests
+              run: docker compose exec app npm test
+
+            - name: Tear down
+              run: docker compose down
+  - language: yaml
+    label: "Verify Docker and Compose versions in workflow"
+    code: |
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check Docker version
+              run: |
+                docker version
+                docker compose version
+                # If docker-compose (v1) is needed, install it explicitly:
+                # pip install docker-compose
+  - language: yaml
+    label: "Pin Docker version for self-hosted runners sensitive to 29.x changes"
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - name: Pin Docker to 28.x (if 29.x breaks your workflow)
+              run: |
+                sudo apt-get remove -y docker-ce docker-ce-cli
+                sudo apt-get install -y docker-ce=5:28.0.4-1~ubuntu.24.04~noble \
+                  docker-ce-cli=5:28.0.4-1~ubuntu.24.04~noble
+prevention:
+  - "Migrate from `docker-compose` (v1) to `docker compose` (v2 plugin) immediately —
+    v1 is no longer maintained and is removed in Docker 29.x images."
+  - "Remove `--compatibility` flags from all Compose invocations; the flag was
+    deprecated and is removed in Compose 2.40.x."
+  - "Subscribe to `actions/runner-images` announcements to get advance notice of
+    Docker version bumps before they land on hosted runners."
+  - "Pin Docker Compose file format version at `version: '3.8'` or later; v2 Compose
+    files have better compatibility with modern Compose plugin versions."
+  - "Test workflows in a local Docker 29.x environment before relying on them in CI
+    to catch API and behavioral differences early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13474"
+    label: "Announcement: Docker 29.1 + Compose 2.40.3 update (runner-images#13474)"
+  - url: "https://github.com/actions/runner-images/issues/14105"
+    label: "Tracking: Ubuntu Docker v29 rollback and re-attempt (runner-images#14105)"
+  - url: "https://docs.docker.com/compose/releases/migrate/"
+    label: "Docker Docs: Migrate from Compose v1 to v2"
+  - url: "https://docs.docker.com/engine/release-notes/29.1/"
+    label: "Docker Engine 29.1 release notes"

package/errors/runner-environment/node-20-toolcache-removal.yml

@@ -0,0 +1,134 @@
+id: runner-environment-029
+title: "Node.js 20 Removed from Runner Image Toolcache — Scripts Break Without setup-node"
+category: runner-environment
+severity: error
+tags:
+  - node
+  - nodejs
+  - toolcache
+  - node20
+  - node22
+  - setup-node
+  - eol
+patterns:
+  - regex: "node.*not found|node: command not found"
+    flags: "i"
+  - regex: "node.*version.*20.*not.*available|node 20.*removed"
+    flags: "i"
+  - regex: "required node.*20|node@20.*not installed"
+    flags: "i"
+  - regex: "engines.*node.*20.*not satisfied"
+    flags: "i"
+error_messages:
+  - "node: command not found"
+  - "The tool 'node' for version spec '20' was not found locally."
+  - "Couldn't resolve the package 'node' to a version matching '20'"
+  - "error engines: The engine \"node\" is incompatible with this module."
+root_cause: |
+  Node.js 20 reached **end-of-life on April 30, 2026**. Starting with runner image
+  releases on **May 18, 2026** (commit 249562679f on actions/runner-images), Node.js 20
+  was removed from the pre-installed toolcache on all runner images (Ubuntu, macOS,
+  Windows).
+
+  **What changed:**
+  - The default system `node` binary on all runner images changed from Node.js **20**
+    to Node.js **22** (Maintenance LTS).
+  - `node 20` is no longer available in the toolcache — `actions/setup-node` will
+    download it from the internet if explicitly requested, or fail if the network is
+    not available (self-hosted runners with restricted network access).
+  - Workflows that use `node` without `actions/setup-node` now get Node 22 by default.
+
+  **Three distinct breakage patterns:**
+
+  1. **Shell scripts calling `node script.js`** — these now run under Node 22, which
+     may break code that relied on Node 20 behavior (e.g., `fetch` API differences,
+     removed experimental APIs, `--openssl-legacy-provider` not available by default).
+
+  2. **`actions/setup-node` without version** — previously defaulted to node-version-
+     file lookup or the installed 20.x; now defaults to the latest LTS (22.x). Any
+     `package.json` `engines` field restricting to `>=20 <21` still works, but strict
+     `20.x` pins will now cause download overhead or failure.
+
+  3. **Self-hosted runners with restricted internet access** — if a workflow requests
+     `node-version: '20'` via `actions/setup-node` and the runner has no internet
+     access to download from nodejs.org, the setup step fails because 20 is no longer
+     in the local toolcache.
+
+  Note: This is distinct from the **action runtime migration** (Node 20 → Node 24 for
+  running JavaScript actions themselves, announced separately). This entry covers the
+  *pre-installed Node.js available to shell scripts*.
+fix: |
+  Update workflows to use Node.js 22 (current Maintenance LTS) or pin an explicit LTS
+  version via `actions/setup-node`.
+
+  **Option 1 — Explicit version pin (recommended for reproducibility):**
+  Add `actions/setup-node` with an explicit `node-version` or `node-version-file`.
+
+  **Option 2 — Use `.nvmrc` or `.node-version` file:**
+  Create a version file in the repo root and use `node-version-file` input.
+
+  **Option 3 — Accept Node 22:**
+  Test your application on Node 22 and update `package.json` `engines` accordingly.
+
+  **For self-hosted runners with no internet:**
+  Pre-install Node.js 22 in the runner's local toolcache directory and point
+  `AGENT_TOOLSDIRECTORY` to it.
+fix_code:
+  - language: yaml
+    label: "Pin explicit Node.js version via actions/setup-node"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'   # or '20' to keep on 20 (downloaded from web)
+                cache: 'npm'
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Use .nvmrc to declare Node version in the repo"
+    code: |
+      # .nvmrc (in repo root)
+      # 22
+
+      # workflow step
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: "Matrix build to verify compatibility across Node versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              node-version: ['20', '22', '24']
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node-version }}
+            - run: npm ci && npm test
+prevention:
+  - "Always use `actions/setup-node` with an explicit `node-version` or
+    `node-version-file` — never rely on the runner's pre-installed Node.js version."
+  - "Add a `.nvmrc` or `.node-version` file to your repository to pin Node.js version
+    for local dev, CI, and Vercel/Netlify deployments simultaneously."
+  - "Watch for Node.js EOL dates at https://github.com/nodejs/release#readme — plan
+    upgrades before the runner image drops the EOL version."
+  - "For self-hosted runners, maintain a local toolcache refresh process whenever a
+    new Node.js LTS is released or an old one reaches EOL."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "Announcement: Node.js 20 removal from runner images (runner-images#14029)"
+  - url: "https://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule — EOL dates"
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node — official action documentation"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/customizing-github-hosted-runners"
+    label: "GitHub Docs: Customizing GitHub-hosted runners"

package/errors/runner-environment/ubuntu-arm64-docker-not-preinstalled.yml

@@ -0,0 +1,137 @@
+id: runner-environment-030
+title: "Ubuntu ARM64 Runner Missing Docker — docker: command not found on arm64"
+category: runner-environment
+severity: error
+tags:
+  - arm64
+  - aarch64
+  - docker
+  - ubuntu
+  - partner-runner
+  - docker-buildx
+  - setup-buildx-action
+patterns:
+  - regex: "docker.*command not found|docker.*not found.*arm64"
+    flags: "i"
+  - regex: "docker/setup-buildx-action.*error|setup-buildx.*arm64.*fail"
+    flags: "i"
+  - regex: "Cannot connect to the Docker daemon|Is the docker daemon running"
+    flags: "i"
+  - regex: "Error: Unable to locate executable file: docker"
+    flags: "i"
+error_messages:
+  - "docker: command not found"
+  - "Error: Unable to locate executable file: docker"
+  - "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"
+  - "exec: \"docker\": executable file not found in $PATH"
+root_cause: |
+  GitHub-hosted **Ubuntu 24.04 ARM64** runner images (available via labels such as
+  `ubuntu-24.04-arm64`, `ubuntu-arm`, or partner runner images for ARM64) do **not**
+  have Docker pre-installed on `PATH`, despite the partner image README listing Docker
+  client and server versions.
+
+  This is a **documentation mismatch** affecting ARM64 runner users (actions/runner-
+  images#14051, created March 2026, still open as of May 2026):
+  - The `partner-runner-images` README lists Docker Client 28.0.4 and Docker Server
+    28.0.4 as installed software.
+  - In practice, `docker` is **not present on `PATH`** in these runners.
+  - The runner is identified as `Source: Partner` and `Base Image for Ubuntu Server
+    24.04`.
+
+  **Affected workflows:**
+  - Any step using `docker build`, `docker run`, `docker pull`, or `docker push`
+    directly in a `run:` block.
+  - `docker/setup-buildx-action@v3` fails because it cannot find the Docker CLI.
+  - Container-based jobs that use the host Docker socket.
+  - Multi-platform builds that need BuildKit on ARM64.
+
+  **x86-64 runners are not affected.** This is specific to ARM64 GitHub-hosted
+  runners using the partner image.
+
+  This is distinct from the `docker-buildx-not-setup.yml` entry (which covers x64
+  runners where Docker BuildKit is present but `buildx` is not configured).
+fix: |
+  Install Docker explicitly at the start of ARM64 workflow jobs, or use a Docker
+  action that handles installation automatically.
+
+  **Option 1 — Install Docker via the official convenience script (fastest):**
+  Run the Docker install script at the start of the job. This adds ~60 seconds to
+  job start time but ensures Docker is available.
+
+  **Option 2 — Use `docker/setup-buildx-action@v3` after Docker install:**
+  After installing Docker, `setup-buildx-action` can then install BuildKit buildx.
+
+  **Option 3 — Use a Docker-pre-installed large runner:**
+  If budget allows, use GitHub's x86-64 larger runners which have Docker pre-installed,
+  or a self-hosted ARM64 runner with Docker pre-configured.
+
+  **Option 4 — Use `runs-on: ubuntu-latest` (x86-64) instead of ARM64:**
+  If ARM64 is not strictly required, run on x86-64 which has Docker pre-installed.
+fix_code:
+  - language: yaml
+    label: "Install Docker on ARM64 runner before using it"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm64
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker
+              run: |
+                curl -fsSL https://get.docker.com -o get-docker.sh
+                sudo sh get-docker.sh
+                sudo usermod -aG docker $USER
+                sudo systemctl start docker
+                docker --version
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Build image
+              run: docker build -t myapp:latest .
+  - language: yaml
+    label: "Cross-platform build with explicit ARM64 Docker install"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - runner: ubuntu-latest
+                  platform: linux/amd64
+                - runner: ubuntu-24.04-arm64
+                  platform: linux/arm64
+                  install_docker: true
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker (ARM64 only)
+              if: matrix.install_docker == true
+              run: |
+                curl -fsSL https://get.docker.com | sudo sh
+                sudo usermod -aG docker $USER
+                sudo systemctl enable --now docker
+
+            - name: Build for ${{ matrix.platform }}
+              run: docker build --platform ${{ matrix.platform }} -t myapp .
+prevention:
+  - "Before adding `runs-on: ubuntu-24.04-arm64` to a workflow that uses Docker,
+    verify Docker availability by running `docker --version` in a test job."
+  - "Check the current partner runner image README at
+    https://github.com/actions/partner-runner-images before relying on pre-installed
+    tooling on non-standard runner images."
+  - "Consider using self-hosted ARM64 runners with Docker pre-configured for
+    production workloads that depend on Docker on ARM64."
+  - "Track the open issue (actions/runner-images#14051) for when GitHub adds Docker
+    to ARM64 partner images natively."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14051"
+    label: "Issue: Ubuntu 24.04 ARM64 missing Docker (runner-images#14051)"
+  - url: "https://github.com/actions/partner-runner-images"
+    label: "actions/partner-runner-images — partner runner image definitions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: GitHub-hosted runner specifications"
+  - url: "https://docs.docker.com/engine/install/ubuntu/"
+    label: "Docker Docs: Install Docker Engine on Ubuntu"

package/errors/runner-environment/windows-2019-runner-retirement.yml

@@ -0,0 +1,100 @@
+id: runner-environment-028
+title: "windows-2019 Runner Retired — Jobs Fail with No Runner Found"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-2019
+  - runner-retirement
+  - deprecation
+  - runs-on
+  - migration
+patterns:
+  - regex: "No runner matching the requested labels.*windows-2019"
+    flags: "i"
+  - regex: "Could not find any runner matching.*windows-2019"
+    flags: "i"
+  - regex: "windows-2019.*is no longer supported"
+    flags: "i"
+  - regex: "windows-2019.*deprecated.*unsupported"
+    flags: "i"
+error_messages:
+  - "No runner matching the requested labels was found: windows-2019"
+  - "Could not find any runner matching the requested labels: [windows-2019]"
+  - "This request was automatically failed because 'windows-2019' is no longer available."
+root_cause: |
+  GitHub retired the `windows-2019` runner image on **June 30, 2025** following the
+  GitHub Actions N-1 OS support policy (only the latest two major versions of each OS
+  are hosted).
+
+  **Timeline:**
+  - **2025-04-15**: Deprecation announcement (actions/runner-images#12045)
+  - **2025-06-01**: Deprecation begins — longer queue times during peak hours
+  - **Between June 1–30**: GitHub temporarily fails jobs using `windows-2019` to raise
+    awareness in advance of the hard removal
+  - **2025-06-30**: `windows-2019` fully unsupported — all jobs using this label fail
+
+  Workflows that explicitly specify `runs-on: windows-2019` (or any combination like
+  `[self-hosted, windows-2019]` on non-self-hosted runners) will fail immediately after
+  the retirement date. Workflows that used `windows-latest` were not affected since
+  `windows-latest` already pointed to `windows-2022`.
+
+  The replacement is `windows-2022` (already the current `windows-latest` at time of
+  retirement) or `windows-2025` (Windows Server 2025 image).
+fix: |
+  Update all `runs-on` references from `windows-2019` to `windows-2022` or
+  `windows-2025` (or use `windows-latest`).
+
+  **Migration path:**
+  - `windows-2019` → `windows-2022` (minimal change, widely compatible)
+  - `windows-2019` → `windows-2025` (latest; check for VS 2026 path changes if using
+    hardcoded MSVC paths)
+  - `windows-2019` → `windows-latest` (tracks latest, reduces future manual migrations)
+
+  **Before migrating**, verify that your workflow does not depend on Windows Server 2019
+  -specific behavior such as:
+  - VS 2019 toolchain at `C:\Program Files (x86)\Microsoft Visual Studio\2019\`
+  - Older .NET Framework SDK versions not present on 2022 or 2025 images
+  - Windows Server 2019-specific APIs or registry keys
+fix_code:
+  - language: yaml
+    label: "Replace windows-2019 with windows-2022"
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: windows-2019
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyApp.sln /p:Configuration=Release
+  - language: yaml
+    label: "Use windows-latest to avoid future manual migrations"
+    code: |
+      jobs:
+        build:
+          # windows-latest currently points to windows-2025 (as of June 2026)
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: bash
+    label: "Audit all workflows for windows-2019 references"
+    code: |
+      # Find all workflow files using windows-2019
+      grep -r "windows-2019" .github/workflows/
+prevention:
+  - "Use `windows-latest` instead of pinned OS versions unless you have a specific
+    reason to pin. This avoids retirement failures entirely."
+  - "Subscribe to the `actions/runner-images` repository announcements to receive
+    deprecation notices before they become hard failures."
+  - "When you must pin an OS version, add a calendar reminder or Renovate/Dependabot
+    rule to review the pin when the N-1 policy applies."
+  - "Run a periodic repository search for retired runner labels:
+    `grep -r 'windows-2019\\|ubuntu-20.04\\|macos-12' .github/workflows/`"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12045"
+    label: "Announcement: Windows 2019 deprecation and retirement (runner-images#12045)"
+  - url: "https://github.blog/changelog/2025-04-15-upcoming-breaking-changes-and-releases-for-github-actions/"
+    label: "GitHub Changelog: Windows Server 2019 is closing down"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Supported GitHub-hosted runners"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",