@htekdev/actions-debugger 1.0.128 → 1.0.130

package/errors/caching-artifacts/caching-artifacts-076.yml

@@ -0,0 +1,141 @@
+id: caching-artifacts-076
+title: 'actions/cache 429 rate limit on restore not retried — workflow silently falls through to cache miss'
+category: caching-artifacts
+severity: warning
+tags:
+  - actions-cache
+  - rate-limit
+  - 429
+  - restore
+  - cache-miss
+  - silent-fallthrough
+patterns:
+  - regex: 'Failed to restore.*Rate limited.*429|rate limit exceeded.*GetCacheEntryDownloadURL'
+    flags: 'i'
+  - regex: 'You.ve hit a rate limit.*rate limit will reset'
+    flags: 'i'
+  - regex: 'Failed to GetCacheEntryDownloadURL.*Too Many Requests'
+    flags: 'i'
+error_messages:
+  - "Warning: You've hit a rate limit, your rate limit will reset in 18 seconds"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited: Failed request: (429) Too Many Requests: rate limit exceeded"
+  - "Cache not found for input keys: <key>"
+root_cause: |
+  When the GitHub Actions cache service returns HTTP 429 (Too Many Requests) on the
+  **restore/download path**, `actions/cache` does NOT implement retry logic for this
+  specific error. Instead, it:
+
+  1. Logs `Warning: You've hit a rate limit, your rate limit will reset in X seconds`
+  2. Logs `Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited`
+  3. Falls through to `Cache not found for input keys: <key>` — treating it as a cache miss
+  4. Continues workflow execution as if the cache doesn't exist
+
+  **Important distinction from upload 429:** The existing entry `cache-service-429-upload-ebadf-crash.yml`
+  covers HTTP 429 during cache UPLOAD causing an EBADF crash (a different, harder failure).
+  This entry covers 429 during cache RESTORE, which silently falls through without crashing
+  but causes unnecessary full rebuilds.
+
+  **Impact:** Workflows with many concurrent runs hitting the same cache key simultaneously
+  (e.g. a heavily-used monorepo's `node_modules` or `~/.cargo/registry` cache) can exceed
+  the per-key request rate limit. All concurrent runs that get rate-limited then execute a
+  full dependency install/build from scratch, multiplying CI time and cost. The 429 response
+  includes a reset time in the warning message but `actions/cache` ignores it.
+
+  **When it happens:** Most commonly seen in:
+  - Monorepos with many parallel jobs all restoring the same cache key
+  - High-frequency push workflows where many runs are active simultaneously
+  - Nightly builds on large teams where multiple jobs race for the same cache
+
+  Source: actions/cache#1758 (May 13, 2026), also reported via oxidecomputer/hubris#2535
+fix: |
+  No retry mechanism exists in `actions/cache` for restore-path 429 errors. The
+  following strategies reduce exposure:
+
+  **Option 1: Add job-level cache-key uniqueness to reduce simultaneous key contention**
+
+  Use a cache key that includes the job name or runner index, so parallel runs don't all
+  hit the exact same cache entry at once.
+
+  **Option 2: Add a retry wrapper around the restore step**
+
+  Use a loop + `cache-hit` output check to retry on miss within a reasonable window.
+
+  **Option 3: Use `actions/cache/restore` + `actions/cache/save` split and add `fail-on-cache-miss: false`**
+
+  Explicitly handle the miss and emit a warning rather than silently rebuilding.
+
+  **Option 4: File a +1 on actions/cache#1758**
+
+  The correct fix is for `actions/cache` to detect the 429 reset time and wait/retry
+  instead of falling through. Adding reactions encourages prioritization.
+fix_code:
+  - language: yaml
+    label: 'Recognize the 429 pattern and add explicit retry logic'
+    code: |
+      # The standard cache step falls through silently on 429.
+      # Add a retry wrapper to explicitly detect and retry:
+      steps:
+        - name: Restore cache (with 429 retry)
+          id: cache-restore
+          uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-
+
+        # Detect rate-limit fallthrough: cache appears to miss but key exists
+        - name: Retry cache if rate-limited
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          uses: actions/cache/restore@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-
+
+  - language: yaml
+    label: 'Reduce cache contention — add job index to key for parallel runs'
+    code: |
+      # When many parallel jobs restore the same cache key, add job uniqueness
+      # to distribute reads across different cache entries:
+      strategy:
+        matrix:
+          shard: [1, 2, 3, 4]
+
+      steps:
+        - uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            # Use matrix shard to reduce simultaneous same-key requests
+            key: ${{ runner.os }}-node-shard${{ matrix.shard }}-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-shard${{ matrix.shard }}-
+              ${{ runner.os }}-node-
+  - language: yaml
+    label: 'Observe the rate limit in workflow logs'
+    code: |
+      # What the rate limit looks like in workflow output:
+      # (these are Warning lines, not Error — easy to miss)
+      #
+      # Run actions/cache@v4
+      # Received 0 cache(s) from cache.githubusercontent.com
+      # Warning: You've hit a rate limit, your rate limit will reset in 18 seconds
+      # Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited:
+      #          Failed request: (429) Too Many Requests: rate limit exceeded
+      # Cache not found for input keys: linux-node-abc123, linux-node-
+      #
+      # The workflow then continues as if cache was never created.
+      # Silent "success" hides wasted rebuild time.
+prevention:
+  - "When running many parallel jobs on a shared cache key, add per-job cache key suffixes (e.g. matrix index, job name) to distribute read load across different cache entries."
+  - "Monitor CI timing for unexplained slowdowns — a sudden increase in dependency install time across all parallel jobs is a signal that cache restoration is being rate-limited."
+  - "Cache keys with very high read frequency (multiple runs per minute across many jobs) are most susceptible. Use granular keys to avoid this."
+  - "Check that your cache key is stable (not changing per-run) — flapping keys force repeated cache service requests for new key registrations, increasing rate limit exposure."
+docs:
+  - url: 'https://github.com/actions/cache/issues/1758'
+    label: 'actions/cache#1758 — Handle rate limit on restore (no retry implemented)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy'
+    label: 'GitHub Docs: Cache usage limits and eviction policy'
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache repository'

package/errors/caching-artifacts/caching-artifacts-077.yml

@@ -0,0 +1,158 @@
+id: caching-artifacts-077
+title: 'upload-artifact fails with "Bad Request" on self-hosted runners behind HTTPS proxy — Azure BlobClient not configured with proxy transport'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - proxy
+  - https-proxy
+  - azure-blob
+  - self-hosted
+  - bad-request
+patterns:
+  - regex: 'Error: Bad Request.*upload.*artifact|upload.*artifact.*Error: Bad Request'
+    flags: 'i'
+  - regex: 'BlobClient.*proxy|blob.*core.*windows.*proxy.*Bad Request'
+    flags: 'i'
+  - regex: 'Beginning upload of artifact content to blob storage[\s\S]*?Error: Bad Request'
+    flags: 'i'
+error_messages:
+  - "Error: Bad Request"
+  - "Beginning upload of artifact content to blob storage\nError: Bad Request"
+  - "Uploading artifact: <name>\nBeginning upload of artifact content to blob storage\nError: Bad Request"
+root_cause: |
+  When `HTTPS_PROXY` (or `https_proxy`) is set in the self-hosted runner environment,
+  `actions/upload-artifact` (v4+) fails with `Error: Bad Request` during the blob upload
+  step.
+
+  **Root cause:** `@actions/artifact` creates an Azure `BlobClient` from `@azure/storage-blob`
+  using only the pre-signed upload URL — no proxy transport configuration is passed:
+
+  ```typescript
+  const blobClient = new BlobClient(authenticatedUploadURL)
+  const blockBlobClient = blobClient.getBlockBlobClient()
+  ```
+
+  The Azure SDK creates its own internal HTTP pipeline that does not honor the environment's
+  `HTTPS_PROXY` variable. The CONNECT tunnel may appear to succeed (proxy returns 200) but
+  the Azure SDK's TLS negotiation through the proxy tunnel fails or sends incorrect frames,
+  producing a `Bad Request` response after a ~75-second stall.
+
+  **Affected actions:** Any action using `@actions/artifact` for blob uploads:
+  - `actions/upload-artifact` v4+
+  - Any third-party action built on `@actions/artifact`
+
+  **Same root cause in the runner itself:** The runner's C# `BlobClient` also lacks proxy
+  transport configuration, causing step logs and diagnostic uploads to stall similarly
+  (see actions/runner#4351).
+
+  **Proxy logs show the pattern:**
+  ```
+  CONNECT productionresultssa6.blob.core.windows.net:443 → status=200 (ALLOWED)
+    requestSize=~17 KB  (partial upload)
+    latency=~75 seconds  (stalled, not completing)
+  ```
+
+  **curl and Python upload the same blob endpoint in <1s through the same proxy** — the
+  issue is specific to the Azure SDK's pipeline construction when created without proxy opts.
+
+  Source: actions/toolkit#2377 (Apr 15, 2026), actions/runner#4351
+fix: |
+  **Workaround (recommended): Add `.blob.core.windows.net` to NO_PROXY**
+
+  Bypass the proxy for Azure Blob Storage traffic. Artifacts upload directly to Azure Blob
+  Storage endpoints (`*.blob.core.windows.net`), not through `api.github.com`.
+
+  Set `NO_PROXY` in the runner's environment (`.env` file, systemd unit, or runner config):
+  ```
+  NO_PROXY=.blob.core.windows.net,.actions.githubusercontent.com
+  ```
+
+  **Important:** This bypasses proxy inspection for Azure Blob traffic. If your security
+  policy requires proxy inspection for all egress, you must configure the proxy to pass
+  TLS-tunneled connections to `*.blob.core.windows.net` without re-signing.
+
+  **Permanent fix (pending upstream):**
+  The `@actions/artifact` package needs to pass `proxyOptions` when constructing `BlobClient`.
+  Monitor actions/toolkit#2377 for the fix. Once released, upgrading to the fixed version
+  of `actions/upload-artifact` will resolve the issue without needing `NO_PROXY`.
+fix_code:
+  - language: yaml
+    label: 'Workaround — set NO_PROXY to bypass proxy for Azure Blob Storage'
+    code: |
+      # In your runner's .env file (located at: <runner-dir>/.env)
+      # Add Azure Blob Storage and GitHub Actions results endpoints to NO_PROXY:
+      #
+      # HTTPS_PROXY=http://your-proxy:8080
+      # NO_PROXY=.blob.core.windows.net,.actions.githubusercontent.com,localhost,127.0.0.1
+      #
+      # Restart the runner service after editing .env:
+      #   sudo ./svc.sh stop
+      #   sudo ./svc.sh start
+
+      # If using ARC/Kubernetes, set as environment variables in the runner pod spec:
+      # spec:
+      #   containers:
+      #   - name: runner
+      #     env:
+      #     - name: HTTPS_PROXY
+      #       value: "http://your-proxy:8080"
+      #     - name: NO_PROXY
+      #       value: ".blob.core.windows.net,.actions.githubusercontent.com"
+
+  - language: yaml
+    label: 'Set NO_PROXY in the workflow as a fallback for managed runners'
+    code: |
+      # For managed self-hosted runners where you cannot edit the .env file,
+      # set NO_PROXY as a job-level env override before the upload step.
+      # Note: This only applies to workflow steps, not the runner service itself.
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          env:
+            # Ensure Azure Blob Storage bypasses proxy for artifact uploads
+            NO_PROXY: '.blob.core.windows.net,.actions.githubusercontent.com'
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: 'Confirm the root cause from workflow logs'
+    code: |
+      # Affected workflow output looks like:
+      #
+      # Run actions/upload-artifact@v4
+      # With the provided path, there will be 1 file uploaded
+      # Artifact name is valid!
+      # Root directory input is valid!
+      # Uploading artifact: my-artifact
+      # Beginning upload of artifact content to blob storage
+      # Error: Bad Request
+      #
+      # The "Beginning upload of artifact content to blob storage" line appears
+      # followed immediately (after ~75 seconds) by "Error: Bad Request".
+      # No detailed error, no retry, no stack trace.
+      #
+      # Workaround confirmation — after setting NO_PROXY correctly:
+      #
+      # Uploading artifact: my-artifact
+      # Beginning upload of artifact content to blob storage
+      # Artifact upload has finished successfully.
+      # Artifact 'my-artifact' has been successfully uploaded!
+prevention:
+  - "When deploying self-hosted runners behind a corporate HTTPS proxy, always configure `NO_PROXY` to include `.blob.core.windows.net` — this is where GitHub Actions stores artifacts and build outputs."
+  - "Test artifact upload and download on a new self-hosted runner deployment before declaring it production-ready. A quick test workflow with `actions/upload-artifact` and `actions/download-artifact` will reveal proxy issues immediately."
+  - "Include `.actions.githubusercontent.com` and `.blob.core.windows.net` in your proxy allow-list or NO_PROXY config — these are required for GitHub Actions to function correctly."
+  - "Monitor actions/toolkit#2377 for the upstream fix that adds proxy transport configuration to the Azure BlobClient. Once released, upgrade `actions/upload-artifact` to the fixed version."
+docs:
+  - url: 'https://github.com/actions/toolkit/issues/2377'
+    label: 'actions/toolkit#2377 — BlobClient upload fails with "Bad Request" through HTTPS proxy'
+  - url: 'https://github.com/actions/runner/issues/4351'
+    label: 'actions/runner#4351 — Runner Azure Blob uploads stall through HTTPS proxy (same root cause)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#internet-access-for-self-hosted-runners'
+    label: 'GitHub Docs: Internet access requirements for self-hosted runners'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow'
+    label: 'GitHub Docs: Using self-hosted runners in a workflow'

package/errors/runner-environment/runner-environment-239.yml

@@ -0,0 +1,121 @@
+id: runner-environment-239
+title: 'setup-python fails on Ubuntu 26.04 container in self-hosted runners — Python version not in manifest'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - ubuntu-26
+  - manifest
+  - self-hosted
+  - container
+  - python-version
+patterns:
+  - regex: 'The version.*with architecture.*was not found for this operating system'
+    flags: 'i'
+  - regex: 'setup-python.*ubuntu.*26|ubuntu.*26.*setup-python'
+    flags: 'i'
+  - regex: 'version.*not found.*operating system.*ubuntu'
+    flags: 'i'
+error_messages:
+  - "Error: The version '3.13' with architecture 'x64' was not found for this operating system."
+  - "Error: The version '3.12' with architecture 'x64' was not found for this operating system."
+  - "Error: The version '3.11' with architecture 'x64' was not found for this operating system."
+root_cause: |
+  When a new Ubuntu LTS version (e.g. 26.04) is released, pre-built Python binaries for
+  that OS are NOT immediately added to the versions manifest at
+  `https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json`.
+
+  `actions/setup-python` reads this manifest to locate and download pre-compiled Python
+  binaries matching the requested version and architecture. When the running OS identifier
+  is not present in the manifest, all version requests fail — even for Python versions that
+  exist for other Ubuntu releases (22.04, 24.04).
+
+  **Why GitHub-hosted runners succeed:** On GitHub-hosted `ubuntu-latest` runners, Python
+  versions are pre-installed in the toolcache. `setup-python` resolves from cache without
+  downloading, so the missing manifest entry doesn't matter.
+
+  **Why self-hosted runners fail:** Self-hosted runners typically don't have pre-installed
+  toolcaches. When `setup-python` tries to download the version for the container OS, the
+  manifest lookup fails because `ubuntu-26.04` is absent.
+
+  This is a recurring pattern. The same issue occurred when Ubuntu 24.04 launched
+  (see setup-python#854). Pre-built binaries are added only after the runner image reaches
+  general availability in `actions/runner-images`, which lags the OS release.
+
+  **Affected configurations:**
+  - `runs-on: [self-hosted]` + `container: ubuntu:latest` (resolves to Ubuntu 26.04)
+  - `runs-on: [self-hosted]` + `container: ubuntu:26.04`
+  - Any self-hosted runner setup where Python must be downloaded on demand for ubuntu 26.04
+
+  Source: actions/setup-python#1309 (May 5, 2026)
+fix: |
+  **Option 1 (recommended, temporary): Pin container to Ubuntu 24.04**
+
+  Until Ubuntu 26.04 Python binaries are added to the versions manifest, use an explicit
+  Ubuntu 24.04 container. This is the fastest fix with no other workflow changes.
+
+  **Option 2: Use a GitHub-hosted runner for Python setup**
+
+  GitHub-hosted `ubuntu-latest` runners have Python pre-installed in the toolcache and do
+  not require a manifest download. If you need a self-hosted runner for other reasons, you
+  can split: run setup-python on a hosted runner and transfer artifacts to the self-hosted
+  runner.
+
+  **Option 3: Pre-install Python in your container image**
+
+  Build a custom container image with Python pre-installed (via `apt`, `deadsnakes`, or
+  `pyenv`) so `setup-python` finds it in the system Python path rather than downloading.
+
+  **Option 4: Wait for manifest update**
+
+  Ubuntu 26.04 Python binaries will be added to the manifest after `ubuntu-26.04` reaches
+  GA status in `actions/runner-images`. Monitor setup-python#1309 for the fix notification.
+fix_code:
+  - language: yaml
+    label: 'Workaround — pin container to Ubuntu 24.04 until Ubuntu 26.04 is in manifest'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          # Pin to ubuntu:24.04 until ubuntu:26.04 is in the versions manifest
+          # Unpin once actions/setup-python#1309 is resolved
+          container: ubuntu:24.04   # was: ubuntu:latest or ubuntu:26.04
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v6
+              with:
+                python-version: '3.13'
+            - run: python --version
+  - language: yaml
+    label: 'Alternative — pre-install Python in a custom container image'
+    code: |
+      # Dockerfile — base image with Python already installed
+      FROM ubuntu:26.04
+      RUN apt-get update && apt-get install -y python3.13 python3.13-venv python3-pip && \
+          ln -s /usr/bin/python3.13 /usr/bin/python
+      # In workflow: container: your-registry/ubuntu-python:26.04
+      # Then skip actions/setup-python entirely — Python is pre-installed
+
+      # workflow.yml
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          container: your-registry/ubuntu-python:26.04
+          steps:
+            - uses: actions/checkout@v4
+            # No setup-python needed — Python already in container
+            - run: python --version
+prevention:
+  - "When using `ubuntu:latest` as a container image, be aware that it will track the latest Ubuntu release. On new LTS releases, pin to an explicit version (e.g. `ubuntu:24.04`) until `actions/setup-python` adds manifest support."
+  - "Subscribe to the relevant `actions/setup-python` issues when Ubuntu LTS versions are released — Python manifest support lags by several weeks after the GA runner image is available."
+  - "If your self-hosted runners MUST use the newest Ubuntu release, pre-install Python in your base container image rather than relying on `setup-python` to download it."
+  - "Check the versions manifest directly to confirm OS support before adopting new Ubuntu versions in CI: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json"
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1309'
+    label: 'setup-python#1309 — Failing to fetch version from manifest when using Ubuntu 26.04 container'
+  - url: 'https://github.com/actions/setup-python/issues/854'
+    label: 'setup-python#854 — Same issue when Ubuntu 24.04 launched (historical precedent)'
+  - url: 'https://github.com/actions/python-versions/blob/main/versions-manifest.json'
+    label: 'Python versions manifest — check OS support'
+  - url: 'https://docs.github.com/en/actions/using-containerized-services/about-service-containers'
+    label: 'GitHub Docs: About service containers'

package/errors/runner-environment/runner-environment-240.yml

@@ -0,0 +1,140 @@
+id: runner-environment-240
+title: 'ARC v0.14.1 listener pods enter infinite crash-loop after upgrade — scaleset v0.3.0 treats broker EOF as fatal'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - kubernetes
+  - listener
+  - crash-loop
+  - scaleset
+  - ephemeral-runners
+patterns:
+  - regex: 'Listener pod is terminated.*reason.*Error'
+    flags: 'i'
+  - regex: 'scaleset.*v0\.3\.[0-9].*EOF|EOF.*broker.*fatal|EOF.*scaleset.*crash'
+    flags: 'i'
+  - regex: 'AutoscalingListener.*recreate.*loop|listener.*restart.*loop'
+    flags: 'i'
+error_messages:
+  - 'Listener pod is terminated  {"reason": "Error", "message": ""}'
+  - 'level=FATAL source=github.com/actions/scaleset@v0.3.0/listener/listener.go msg="EOF from broker"'
+  - 'AutoscalingListener: listener terminated unexpectedly, recreating'
+root_cause: |
+  ARC (Actions Runner Controller) v0.14.1 upgraded the internal `scaleset` library from
+  v0.2.0 to v0.3.0. The v0.3.0 library introduced a "Restore job acquisition flow" change
+  (scaleset PR #90) that treats **EOF responses from the GitHub Actions broker service**
+  (`broker.actions.githubusercontent.com`) as a **fatal error** instead of a transient
+  condition to retry.
+
+  **Before v0.3.0 (ARC v0.14.0):** EOF from the broker long-poll endpoint was treated as a
+  reconnect signal — the listener would gracefully retry the connection and continue.
+
+  **After v0.3.0 (ARC v0.14.1):** EOF causes the listener to exit with a non-zero status
+  code. The ARC controller detects the pod termination via `Listener pod is terminated`
+  with `reason: "Error"` and immediately recreates the listener pod. The new pod hits
+  another EOF and crashes again — producing an infinite restart loop.
+
+  **Note:** scaleset v0.4.0 does NOT fix this. It addresses a different (message ordering)
+  issue. The EOF-as-fatal regression is still present in v0.4.0.
+
+  **Impact:** All `AutoscalingRunnerSet` resources in the cluster enter crash-loop behavior.
+  Jobs queue but no runners are dispatched. Production ARC deployments can accumulate dozens
+  of error terminations within a 30-60 minute window.
+
+  **GitHub-hosted runners are unaffected** — this only impacts organizations using ARC
+  (self-hosted Kubernetes runners) via Helm chart `gha-runner-scale-set-controller`.
+
+  Source: actions/actions-runner-controller#4488 (May 6, 2026, 4 reactions)
+fix: |
+  **Option 1 (recommended): Downgrade to ARC v0.14.0**
+
+  Roll back the `gha-runner-scale-set-controller` Helm chart to the previous stable version:
+
+  ```
+  helm upgrade gha-runner-scale-set-controller \
+    --namespace arc-systems \
+    actions-runner-controller/gha-runner-scale-set-controller \
+    --version 0.14.0
+  ```
+
+  **Option 2: Wait for ARC v0.14.2+ with the EOF fix**
+
+  Monitor the ARC changelog and release notes at:
+  https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog
+
+  **Option 3 (partial mitigation): Reduce listener restart pressure**
+
+  Set `minRunners: 0` on affected `AutoscalingRunnerSet` resources to reduce the frequency
+  of broker long-poll connections that can EOF. This reduces symptom frequency but does
+  not eliminate the crash-loop.
+
+  **How to confirm the root cause:**
+  Check controller logs in the `arc-systems` namespace:
+  ```
+  kubectl logs -n arc-systems -l app=gha-runner-scale-set-controller --since=1h | grep "terminated"
+  ```
+  If you see repeated `Listener pod is terminated {"reason": "Error"}` entries cycling
+  every 1-5 minutes, this is the scaleset v0.3.0 EOF regression.
+fix_code:
+  - language: yaml
+    label: 'Identify crash-loop in controller logs'
+    code: |
+      # Check controller logs for the crash-loop pattern
+      # kubectl logs -n arc-systems deployment/gha-runner-scale-set-controller
+      # Look for repeated:
+      #   Listener pod is terminated  {"reason": "Error", "message": ""}
+      #   AutoscalingListener: recreating listener pod
+
+      # Also check the listener pod itself before it's deleted:
+      # kubectl logs -n arc-systems <listener-pod-name>
+      # Look for scaleset@v0.3.0 in the source path:
+      #   time=... source=github.com/actions/scaleset@v0.3.0/listener/listener.go:179
+      #            msg="Getting next message"
+  - language: yaml
+    label: 'Downgrade ARC controller Helm chart to v0.14.0'
+    code: |
+      # Downgrade via Helm — replace the controller chart version
+      # helm upgrade gha-runner-scale-set-controller \
+      #   --namespace arc-systems \
+      #   actions-runner-controller/gha-runner-scale-set-controller \
+      #   --version 0.14.0
+
+      # Or in your values/ArgoCD/Flux manifest, pin the chart version:
+      # Chart.yaml / helmrelease / kustomize reference:
+      apiVersion: helm.toolkit.fluxcd.io/v2
+      kind: HelmRelease
+      metadata:
+        name: gha-runner-scale-set-controller
+        namespace: arc-systems
+      spec:
+        chart:
+          spec:
+            chart: gha-runner-scale-set-controller
+            version: '0.14.0'   # Pin until EOF crash-loop is fixed in 0.14.2+
+            sourceRef:
+              kind: HelmRepository
+              name: actions-runner-controller
+  - language: yaml
+    label: 'Partial mitigation — set minRunners to 0 to reduce EOF pressure'
+    code: |
+      # gha-runner-scale-set values.yaml
+      # Reducing minRunners to 0 means the listener doesn't stay
+      # permanently connected to the broker, reducing EOF frequency.
+      # NOT a full fix — crash-loop still occurs but less frequently.
+      githubConfigUrl: 'https://github.com/<org>'
+      minRunners: 0     # Reduce from default to limit constant broker connections
+      maxRunners: 10
+prevention:
+  - "Before upgrading ARC to a new minor version, review the changelog at https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog for breaking changes in the scaleset library."
+  - "Deploy ARC upgrades to a staging cluster first. Monitor listener pod restarts for 30-60 minutes before rolling out to production."
+  - "Set up alerting on `Listener pod is terminated` log patterns in your ARC controller namespace — frequent terminations signal a crash-loop before it causes widespread job queuing failures."
+  - "Subscribe to release notifications for `actions/actions-runner-controller` to receive timely notice of regression fixes."
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4488'
+    label: 'ARC#4488 — Listener pods crash-loop after upgrading to ARC v0.14.1 (4 reactions)'
+  - url: 'https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog'
+    label: 'ARC Changelog — gha-runner-scale-set-controller release notes'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors'
+    label: 'GitHub Docs: Troubleshooting Actions Runner Controller errors'

package/errors/runner-environment/runner-environment-241.yml

@@ -0,0 +1,154 @@
+id: runner-environment-241
+title: 'Docker container fails with "openat etc/passwd: path escapes from parent" on containerd v2.2+'
+category: runner-environment
+severity: error
+tags:
+  - containerd
+  - docker
+  - healthcheck
+  - path-escapes
+  - nixos
+  - absolute-symlink
+  - runner-image-update
+patterns:
+  - regex: 'openat etc/passwd: path escapes from parent'
+    flags: 'i'
+  - regex: 'openat etc/group: path escapes from parent'
+    flags: 'i'
+  - regex: 'ExitCode.*-1.*path escapes|path escapes.*ExitCode.*-1'
+    flags: 'i'
+  - regex: 'mount callback failed.*path escapes from parent'
+    flags: 'i'
+error_messages:
+  - "openat etc/passwd: path escapes from parent"
+  - "openat etc/group: path escapes from parent"
+  - "mount callback failed on /tmp/containerd-mount...: openat etc/passwd: path escapes from parent"
+  - "ExitCode: -1 (exit code -1)"
+root_cause: |
+  containerd v2.2.0+ (built with Go 1.24) introduced stricter path validation via Go 1.24's
+  `os.Root` API. When Docker starts or runs a health check on a container whose image has
+  `/etc/passwd` or `/etc/group` symlinked to an **absolute path** (e.g., NixOS images where
+  `/etc/passwd → /nix/store/.../passwd`), containerd misinterprets the symlink target as
+  escaping the container root filesystem and raises:
+  `openat etc/passwd: path escapes from parent`.
+
+  **Affected container images:**
+  - **NixOS-based images** (e.g., `nixos/nix:latest`) — `/etc/passwd → /nix/store/.../passwd`
+  - **ngrok container images** — use absolute symlinks for system files
+  - **Android emulator images** — `/etc` itself may be an absolute symlink to `/system/etc`
+  - Any image where the symlink target for `/etc/passwd` or `/etc/group` starts with `/`
+
+  **Impact on GitHub Actions workflows:**
+  1. Service containers with HEALTHCHECK definitions fail with `ExitCode: -1` even when the
+     service is actually running correctly
+  2. Container jobs (`container: image: nixos/nix:latest`) fail at startup before any steps run
+  3. Docker `run` steps using affected images fail with `path escapes from parent` in logs
+
+  **Status on GitHub-hosted runners:**
+  - **Windows runners** (windows-2022, windows-2025, windows-11-arm64): containerd v2.2.x
+    shipped with Docker 29 on February 9, 2026 — **currently affected**
+  - **Ubuntu runners**: containerd v2.2.x deployed February 9, 2026 then **rolled back on
+    February 20, 2026** due to this and related issues (runner-images#13682, #13684, #13691);
+    tracked for re-deployment in runner-images#14105
+
+  A partial fix was merged in containerd v2.2.2 (commit 85b5418e) addressing the case where
+  `/etc/passwd` itself is a direct absolute symlink. However, the case where an **intermediate
+  directory** (e.g., `/etc` is an absolute symlink to `/system/etc`) remains broken and open
+  in containerd#13382 as of May 2026.
+
+  Source: actions/runner-images#13682 (Feb 2026), containerd/containerd#12683,
+  reubeno/brush#999 (real-world GitHub Actions failure)
+fix: |
+  **Option 1 — Convert absolute symlinks to relative in a pre-step (most portable fix):**
+  Add a step before any Docker operations that resolves absolute `/etc/passwd` and
+  `/etc/group` symlinks to relative equivalents inside the container. This approach works
+  even when you cannot modify the container image.
+
+  **Option 2 — Build a derived image with relative symlinks:**
+  Create a `Dockerfile` that `FROM` the affected image and replaces the absolute symlinks
+  with relative ones. This is the most reliable long-term fix when you own the workflow.
+
+  **Option 3 — Use an alternative image without absolute symlinks:**
+  Standard Ubuntu, Debian, and Alpine images use regular files (not symlinks) for
+  `/etc/passwd` and `/etc/group` — they are unaffected. If the workflow can use a
+  different base image, this sidesteps the issue entirely.
+
+  **Option 4 — Pin containerd to v2.1.x on self-hosted runners:**
+  On self-hosted runners where you control Docker/containerd versions, remain on
+  containerd v1.7.x or v2.1.x until containerd v2.2.3+ resolves all absolute symlink cases.
+fix_code:
+  - language: yaml
+    label: 'Workaround — convert absolute /etc symlinks in a pre-step (NixOS/ngrok containers)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          container:
+            image: nixos/nix:latest
+          steps:
+            - name: Fix absolute /etc symlinks (containerd v2.2+ workaround)
+              run: |
+                for f in /etc/passwd /etc/group; do
+                  if [ -L "$f" ]; then
+                    target=$(readlink "$f")
+                    if echo "$target" | grep -q '^/'; then
+                      # Convert absolute symlink to relative
+                      rel=$(python3 -c "import os; print(os.path.relpath('$target', '/etc'))")
+                      ln -sf "$rel" "$f"
+                    fi
+                  fi
+                done
+            - name: Run tests
+              run: nix run nixpkgs#hello
+
+  - language: yaml
+    label: 'Build a derived image that replaces absolute symlinks with relative ones'
+    code: |
+      # Dockerfile.fixed — used for CI to avoid the containerd v2.2 regression:
+      # FROM nixos/nix:latest
+      # RUN for f in /etc/passwd /etc/group; do \
+      #       if [ -L "$f" ]; then \
+      #         target=$(readlink "$f"); \
+      #         rel=$(python3 -c "import os; print(os.path.relpath('$target', '/etc'))"); \
+      #         ln -sf "$rel" "$f"; \
+      #       fi; \
+      #     done
+
+      # In workflow — build derived image first:
+      steps:
+        - name: Build patched image
+          run: docker build -f Dockerfile.fixed -t my-nix-fixed .
+
+        - name: Use patched image
+          run: docker run --rm my-nix-fixed nix run nixpkgs#hello
+
+  - language: yaml
+    label: 'Use Alpine or Debian service container instead of NixOS/ngrok'
+    code: |
+      # Unaffected base images (no absolute symlinks for /etc/passwd):
+      # redis:7-alpine, postgres:16-alpine, debian:bookworm-slim, ubuntu:24.04
+      jobs:
+        test:
+          runs-on: windows-2025    # Docker 29 + containerd v2.2 — always active on Windows
+          services:
+            redis:
+              image: redis:7-alpine
+              options: >-
+                --health-cmd "redis-cli ping"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+prevention:
+  - 'Never use NixOS, ngrok, or Android emulator container images as service containers on Windows runners without the absolute-symlink workaround — Windows runners have had containerd v2.2.x since Feb 2026.'
+  - 'Check if your container image uses absolute /etc/passwd symlinks with: `docker run --rm <image> readlink /etc/passwd`. If the output starts with "/", it will fail on containerd v2.2+.'
+  - 'Use official distribution base images (Alpine, Debian, Ubuntu) for service containers when possible — they use regular files for /etc/passwd and are unaffected.'
+  - 'Monitor runner-images#14105 for the Ubuntu Docker 29 re-deployment timeline — once Ubuntu runners re-deploy Docker 29, this issue will re-appear on Linux jobs as well.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13682'
+    label: 'runner-images#13682 — Container healthchecks failing with path escapes on Ubuntu runners'
+  - url: 'https://github.com/containerd/containerd/issues/12683'
+    label: 'containerd#12683 — v2.2.0 fails to create containers with /etc/passwd as absolute symlink'
+  - url: 'https://github.com/containerd/containerd/issues/13382'
+    label: 'containerd#13382 — v2.2+ fails when /etc directory itself is an absolute symlink'
+  - url: 'https://github.com/reubeno/brush/issues/999'
+    label: 'brush#999 — Real-world GitHub Actions failure with nixos/nix container'

package/errors/runner-environment/runner-environment-242.yml

@@ -0,0 +1,131 @@
+id: runner-environment-242
+title: 'Docker Engine v29 raises minimum API to 1.44 — old SDK clients fail with "client version X is too old"'
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-29
+  - api-version
+  - sdk
+  - windows
+  - runner-image-update
+  - python-docker
+patterns:
+  - regex: 'client version \d+\.\d+ is too old\. Minimum supported API version is 1\.4[4-9]'
+    flags: 'i'
+  - regex: 'Error response from daemon: client version.*Minimum supported API version is 1\.4[4-9]'
+    flags: 'i'
+  - regex: 'minimum supported API version.*1\.4[4-9]|API version.*too old.*upgrade your client'
+    flags: 'i'
+error_messages:
+  - "Error response from daemon: client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+  - "Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+  - "Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+root_cause: |
+  Docker Engine v29.0 (released November 2025) raised the **minimum supported Docker daemon
+  API version from 1.24 to 1.44**. Any Docker SDK client that negotiates API version 1.43 or
+  lower receives:
+  `"Error response from daemon: client version 1.41 is too old. Minimum supported API version
+  is 1.44, please upgrade your client to a newer version"`.
+
+  **API version 1.44 corresponds to Docker Engine 23.0**. Any SDK client built against Docker
+  < 23.0 will fail when the daemon is Docker Engine v29+.
+
+  **Impact on GitHub Actions — current status:**
+  - **Windows runners** (windows-2022, windows-2025, windows-11-arm64): Docker 29.x deployed
+    February 9, 2026 — **currently affected on Windows workflows**
+  - **Ubuntu runners**: Docker 29.x rolled back February 20, 2026 due to related issues
+    (runner-images#13682, #13684); re-deployment tracked in runner-images#14105
+
+  **Affected tools and workflows:**
+  - Python `docker` library ≤ 6.1.3 (negotiates API 1.41 by default) — upgrade to ≥ 7.0.0
+  - `google/oss-fuzz` CIFuzz action — uses internal Python docker client negotiating API 1.41;
+    affected every project using `google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master`
+  - Go `github.com/docker/docker/client` packages pinned to Docker < 23.0 API
+  - Any workflow tool, action, or custom script that embeds its own Docker SDK rather than
+    invoking the CLI `docker` command
+  - GitHub Codespaces dev container CI workflows using Docker SDK library in test scripts
+
+  **Note:** This is distinct from the Docker Compose v1/v2 breaking changes (see
+  `docker-29-compose-v2-40-breaking.yml` / re-031), which covers Compose CLI changes.
+  This entry covers SDK API negotiation failures from non-CLI Docker clients.
+
+  Source: google/oss-fuzz#14945 (Feb 2026), actions/runner-images#13474, docker/docs#23910
+fix: |
+  **Option 1 — Upgrade Python docker library to ≥ 7.0.0:**
+  The most common case. Python docker SDK ≥ 7.0.0 negotiates API 1.47+ which is compatible
+  with Docker Engine 29.
+
+  **Option 2 — Use the Docker CLI instead of SDK calls:**
+  Replace Python/Go SDK calls with `docker build`, `docker run`, etc. via `run:` steps. The
+  Docker CLI always negotiates the correct API version with the daemon automatically.
+
+  **Option 3 — Set DOCKER_API_VERSION environment variable:**
+  Some SDKs honor `DOCKER_API_VERSION=1.44` as an override. However this only works if the
+  SDK actually implements the 1.44 protocol — just setting the env var won't upgrade an
+  SDK that doesn't support 1.44.
+
+  **Option 4 — Pin the affected tool to an updated version:**
+  For CIFuzz: the fix was deployed to `google/oss-fuzz` within hours of the issue being
+  reported. Pin `@master` to get the fix, or wait for a tagged release. For any other
+  action/tool embedding Docker SDK, check for an updated release that bumps the SDK.
+fix_code:
+  - language: yaml
+    label: 'Upgrade Python docker SDK in workflow before using it'
+    code: |
+      # The error appears in workflows using Python docker library <= 6.1.3
+      # Example error:
+      #   Error response from daemon: client version 1.41 is too old.
+      #   Minimum supported API version is 1.44
+      steps:
+        - name: Upgrade Docker Python SDK
+          run: pip install 'docker>=7.0.0'
+
+        - name: Run Docker-based tests
+          run: python -m pytest tests/docker/
+
+  - language: yaml
+    label: 'Replace SDK docker.from_env() calls with Docker CLI'
+    code: |
+      # Instead of Python SDK:
+      #   import docker
+      #   client = docker.from_env()
+      #   client.images.build(path='.', tag='my-image')
+      # Use the CLI directly via shell steps:
+      steps:
+        - name: Build Docker image
+          run: docker build -t my-image:latest .
+
+        - name: Run container
+          run: docker run --rm my-image:latest ./run-tests.sh
+
+        - name: Push to registry
+          run: docker push my-image:latest
+
+  - language: yaml
+    label: 'Check Docker API version compatibility in your workflow'
+    code: |
+      # Run this step to diagnose version negotiation issues:
+      steps:
+        - name: Show Docker version information
+          run: |
+            docker version
+            # Server.APIVersion: 1.47  (what the daemon offers)
+            # Client.APIVersion: 1.47  (what the CLI uses — always current)
+            # If using Python sdk: python3 -c "import docker; c=docker.from_env(); print(c.version())"
+            # If sdk prints error about client version, upgrade docker>=7.0.0
+prevention:
+  - 'Avoid embedding Docker SDK client calls in workflow scripts — always prefer the Docker CLI via run: steps, which auto-negotiates the correct API version.'
+  - 'When the Python docker library IS required, pin it to >=7.0.0 in requirements.txt or install it explicitly in a workflow step before use.'
+  - 'Test workflows on windows-2025 before ubuntu re-deployment of Docker 29 — Windows runners already expose the Docker 29 min API 1.44 constraint.'
+  - 'If using google/oss-fuzz CIFuzz, ensure you reference a recent commit — the fix for API 1.41 incompatibility was deployed in Feb 2026.'
+  - 'When adding new tool dependencies that use Docker, check the docker-py version they require and whether it supports API >= 1.44.'
+docs:
+  - url: 'https://github.com/google/oss-fuzz/issues/14945'
+    label: 'oss-fuzz#14945 — CIFuzz fails with client version 1.41 too old after Docker v29 update'
+  - url: 'https://github.com/actions/runner-images/issues/13474'
+    label: 'runner-images#13474 — Docker 29.1.* update announcement (Feb 9, 2026)'
+  - url: 'https://docs.docker.com/reference/api/engine/'
+    label: 'Docker Engine API reference — version compatibility matrix'
+  - url: 'https://github.com/actions/runner-images/issues/14105'
+    label: 'runner-images#14105 — Docker v29 Ubuntu re-deployment tracking issue'

package/errors/runner-environment/runner-environment-243.yml

@@ -0,0 +1,120 @@
+id: runner-environment-243
+title: 'macOS 26 runner — Xcode_26.0.app path does not exist; only Xcode_26.0.1.app is installed'
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - xcode
+  - xcode-select
+  - sdk-not-found
+  - runner-image
+  - ios
+  - version-naming
+patterns:
+  - regex: 'SDK.*Xcode_26\.0\.app.*cannot be located|Xcode_26\.0\.app.*SDK.*cannot be located'
+    flags: 'i'
+  - regex: 'xcode-select.*Xcode_26\.0\.app.*no such file|invalid developer directory.*Xcode_26\.0\.app'
+    flags: 'i'
+  - regex: 'xcodebuild: error: SDK.*Xcode_26\.0[^.1].*cannot be located'
+    flags: 'i'
+  - regex: '/Applications/Xcode_26\.0\.app.*does not exist'
+    flags: 'i'
+error_messages:
+  - "xcodebuild: error: SDK \"/Applications/Xcode_26.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk\" cannot be located."
+  - "xcode-select: error: invalid developer directory '/Applications/Xcode_26.0.app/Contents/Developer'"
+  - "error: '/Applications/Xcode_26.0.app' does not exist or is not a directory"
+root_cause: |
+  On `macos-26` and `macos-26-arm64` runners, Xcode applications are installed with their
+  **full version number including patch** in the directory name:
+  - `Xcode_26.0.1.app` — NOT `Xcode_26.0.app`
+  - `Xcode_26.2.app`
+  - `Xcode_26.4.1.app` — NOT `Xcode_26.4.app`
+
+  Workflows that hardcode `/Applications/Xcode_26.0.app` in `xcode-select --switch` or in
+  `DEVELOPER_DIR` environment variables fail immediately because the path does not exist.
+  No backward-compatible symlink (`Xcode_26.0.app → Xcode_26.0.1.app`) is created.
+
+  **Why this changed:** Starting with Xcode 26, Apple's versioning scheme includes a patch
+  component (major.minor.patch) that is reflected in the installed application directory name
+  when the patch is non-zero. This differs from Xcode 16 and earlier where the directory name
+  omitted the patch (e.g., `Xcode_16.4.app` is actually Xcode 16.4.0).
+
+  **Note on the "26.0" naming gap:** The first generally-available Xcode for macOS 26 was
+  Xcode 26.0.1 (not 26.0.0). This means `Xcode_26.0.app` was never installed — the runner
+  image went straight from having no Xcode 26 to having `Xcode_26.0.1.app`.
+
+  Source: actions/runner-images#13743 (Feb 2026)
+fix: |
+  **Option 1 — Use maxim-lobanov/setup-xcode action (recommended):**
+  This action resolves Xcode paths dynamically from the runner's installed versions and
+  handles the naming scheme automatically. Specify an exact version like `'26.0.1'` or
+  `'latest-stable'`.
+
+  **Option 2 — Hardcode the full version including patch:**
+  Replace `Xcode_26.0.app` with `Xcode_26.0.1.app`. Always check the runner image Readme
+  for the exact installed filename before pinning.
+
+  **Option 3 — List available versions at runtime:**
+  Add a discovery step that lists `/Applications/Xcode*.app/` and uses the result to
+  select the correct version dynamically.
+fix_code:
+  - language: yaml
+    label: 'Use setup-xcode to resolve Xcode path automatically (recommended)'
+    code: |
+      # setup-xcode handles the naming scheme and patches for you
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.0.1'   # full version including patch
+
+            - name: Build
+              run: xcodebuild -scheme MyApp -destination generic/platform=iOS build
+
+  - language: yaml
+    label: 'Pin correct full-patch version in xcode-select --switch'
+    code: |
+      # Wrong — path does not exist on macos-26:
+      # - run: sudo xcode-select --switch /Applications/Xcode_26.0.app/Contents/Developer
+
+      # Correct — include the patch version:
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - name: Select Xcode 26.0.1
+              run: sudo xcode-select --switch /Applications/Xcode_26.0.1.app/Contents/Developer
+
+            - name: Verify Xcode version
+              run: xcodebuild -version
+
+  - language: yaml
+    label: 'Discover installed Xcode versions at runtime'
+    code: |
+      # Add a discovery step to find what is actually installed:
+      steps:
+        - name: List installed Xcode versions
+          run: |
+            echo "Available Xcode installations:"
+            ls -la /Applications/Xcode*.app/ 2>/dev/null | awk '{print $NF}'
+            echo ""
+            echo "Currently selected Xcode:"
+            xcode-select -p
+            xcodebuild -version
+
+prevention:
+  - 'Never hardcode Xcode application directory paths — use maxim-lobanov/setup-xcode@v1 with a specific xcode-version that includes the patch number.'
+  - 'When pinning a path is required, always look up the exact installed path in the runner image Readme: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode'
+  - 'For Xcode 26.x, always include the patch in version strings: "26.0.1" not "26.0", "26.4.1" not "26.4".'
+  - 'Subscribe to runner-images announcements to get advance notice of Xcode version updates that change installed paths.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13743'
+    label: 'runner-images#13743 — Xcode 26.0 symlink not working on macos-26 (Feb 2026)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+    label: 'macOS 26 arm64 runner image Readme — installed Xcode versions'
+  - url: 'https://github.com/maxim-lobanov/setup-xcode'
+    label: 'maxim-lobanov/setup-xcode — recommended action for Xcode version selection'

package/errors/runner-environment/runner-environment-244.yml

@@ -0,0 +1,136 @@
+id: runner-environment-244
+title: 'macOS 26 — iOS/watchOS/tvOS 26.0 simulator runtimes removed when Xcode 26.4 GA deployed'
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - xcode
+  - ios-simulator
+  - simulator-runtime
+  - xcodebuild
+  - runtime-removed
+  - runner-image-update
+patterns:
+  - regex: 'Unable to find a destination matching the provided destination specifier.*OS:26\.0[^.]'
+    flags: 'i'
+  - regex: 'Unable to boot.*Simulator.*26\.0[^.].*unavailable|The destination.*iOS.*26\.0[^.].*not available'
+    flags: 'i'
+  - regex: 'Could not find a simulator runtime for.*26\.0[^.]|No matching destinations for.*OS.*26\.0'
+    flags: 'i'
+  - regex: 'simulator.*OS=26\.0[^.][^0-9].*not found|destination.*platform=iOS Simulator.*OS:26\.0[^.].*unavailable'
+    flags: 'i'
+error_messages:
+  - "xcodebuild: error: Unable to find a destination matching the provided destination specifier: { platform:iOS Simulator, OS:26.0 }"
+  - "Unable to boot the Simulator. The request to boot 'iOS 26.0 Simulator' was denied because the destination is incompatible with this version of Xcode."
+  - "Could not find a simulator runtime for 'iOS 26.0'"
+  - "No matching destinations for { platform:iOS Simulator, OS:26.0 }"
+root_cause: |
+  On April 1, 2026, GitHub merged runner-images PR #13875 which moved Xcode 26.4 from Release
+  Candidate to GA on `macos-26` and `macos-26-arm64` runner images. As part of this change:
+
+  - **Added:** iOS 26.4, watchOS 26.4, tvOS 26.4, visionOS 26.4 simulator runtimes
+  - **Removed:** iOS 26.0.1, watchOS 26.0.1, tvOS 26.0.1, visionOS 26.0.1 simulator runtimes
+
+  GitHub Actions images support **at most three runtime sets per Xcode** due to disk space
+  constraints (documented in macos-15-xcode-simulator-sdk-policy.yml). When a new runtime set
+  is added, the oldest is removed.
+
+  **Affected workflows:**
+  - Workflows that pin `OS:26.0` in xcodebuild `-destination` strings (e.g.,
+    `-destination 'platform=iOS Simulator,name=iPhone 16,OS=26.0'`)
+  - Workflows using `xcrun simctl list runtimes` that previously found `iOS 26.0` and now
+    find only `iOS 26.2` and `iOS 26.4` (or later versions)
+  - `fastlane scan` or similar tools configured with a hardcoded iOS 26.0 simulator target
+  - Any tooling that generates test matrices including `iOS 26.0` destinations
+
+  Simulator runtimes **currently available** on macos-26 after the April 1 change:
+  - iOS 26.2 + watchOS 26.2 + tvOS 26.2 + visionOS 26.2
+  - iOS 26.4 + watchOS 26.4 + tvOS 26.4 + visionOS 26.4
+  (The exact installed runtimes change with each Xcode GA deployment. Always check the runner
+  image Readme for the current set.)
+
+  Source: actions/runner-images PR #13875 (merged April 1, 2026), runner-images#13853
+fix: |
+  **Option 1 — Update destination to use an available runtime version:**
+  Replace `OS:26.0` with `OS:26.4` (or `latest-available`) in xcodebuild destination strings.
+  Pin to a specific available version to avoid future breakage.
+
+  **Option 2 — Use `latest-available` as the OS version:**
+  Some xcodebuild invocations accept `OS:latest-available` as the OS specifier, which picks
+  the newest installed runtime matching the platform. This avoids hard-coding a version.
+
+  **Option 3 — Use the maxim-lobanov/setup-ios-simulator action:**
+  This action can download and install a specific simulator runtime on demand, decoupling
+  your workflow from what is pre-installed on the runner image.
+
+  **Option 4 — Query available runtimes at runtime and select dynamically:**
+  Use `xcrun simctl list runtimes` to discover what is installed before running tests, then
+  construct the `-destination` argument from the actual available runtimes.
+fix_code:
+  - language: yaml
+    label: 'Update destination to latest available simulator runtime'
+    code: |
+      jobs:
+        test-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: 'latest-stable'
+
+            # Wrong — iOS 26.0 runtime no longer installed:
+            # - run: xcodebuild test -scheme MyApp
+            #            -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.0'
+
+            # Correct — use an installed runtime version:
+            - name: Run iOS tests
+              run: |
+                xcodebuild test \
+                  -scheme MyApp \
+                  -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.4'
+
+  - language: yaml
+    label: 'Use latest-available OS version to avoid future runtime removals'
+    code: |
+      # latest-available picks the newest installed runtime automatically:
+      steps:
+        - name: Run iOS tests
+          run: |
+            xcodebuild test \
+              -scheme MyApp \
+              -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest-available'
+
+  - language: yaml
+    label: 'Discover installed simulator runtimes before running tests'
+    code: |
+      # Add a diagnostic step to see what runtimes are available:
+      steps:
+        - name: List installed simulator runtimes
+          run: xcrun simctl list runtimes
+
+        # Example output after April 2026:
+        # == Runtimes ==
+        # iOS 26.2 (26.2) - com.apple.CoreSimulator.SimRuntime.iOS-26-2
+        # iOS 26.4 (26.4) - com.apple.CoreSimulator.SimRuntime.iOS-26-4
+        # watchOS 26.2 ...
+        # (iOS 26.0 is NO LONGER listed)
+
+        - name: Run tests against iOS 26.4
+          run: |
+            xcodebuild test \
+              -scheme MyApp \
+              -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.4'
+prevention:
+  - 'Never hardcode specific iOS/watchOS/tvOS simulator runtime version numbers in xcodebuild destination strings — use OS:latest-available or dynamically query installed runtimes.'
+  - 'Check the macOS runner image Readme before each Xcode GA update to verify which simulator runtime sets are installed: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+  - 'Subscribe to runner-images announcements and PRs that add new Xcode GA versions — they always remove the oldest simulator runtime set.'
+  - 'If you need to test against a specific older runtime, use maxim-lobanov/setup-ios-simulator to download it on demand rather than relying on pre-installed runtimes.'
+docs:
+  - url: 'https://github.com/actions/runner-images/pull/13875'
+    label: 'runner-images PR #13875 — Xcode 26.4 GA: added 26.4 runtimes, removed 26.0.1 runtimes'
+  - url: 'https://github.com/actions/runner-images/issues/13853'
+    label: 'runner-images#13853 — macos-26-arm64 Xcode 26.4 RC missing iOS 26.4 simulator runtime'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+    label: 'macOS 26 arm64 runner image Readme — installed simulators section'

package/package.json

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