@htekdev/actions-debugger 1.0.113 → 1.0.115

package/errors/runner-environment/javascript-actions-alpine-arm64-not-supported.yml

@@ -0,0 +1,121 @@
+id: runner-environment-195
+title: 'JavaScript Actions in Alpine containers not supported on ARM64 runners'
+category: runner-environment
+severity: error
+tags:
+  - alpine
+  - arm64
+  - javascript-action
+  - container
+  - ubuntu-24.04-arm
+  - musl
+patterns:
+  - regex: 'JavaScript Actions in Alpine containers are only supported on x64 Linux runners'
+    flags: 'i'
+  - regex: 'Detected Linux Arm64'
+    flags: 'i'
+  - regex: 'JavaScript Actions in Alpine containers.*Detected Linux'
+    flags: 'i'
+error_messages:
+  - 'Error: JavaScript Actions in Alpine containers are only supported on x64 Linux runners. Detected Linux Arm64'
+root_cause: |
+  The Actions runner's container hook for JavaScript-based actions (actions that use
+  `using: node20` or `using: node24` in their action.yml) includes a hard platform check
+  when the container image is detected as Alpine Linux.
+
+  Alpine Linux uses musl libc instead of glibc. The Node.js binaries bundled inside
+  GitHub-hosted Actions runners are compiled against glibc and cannot run inside Alpine
+  containers without compatibility shims. The runner guards against this by rejecting
+  JavaScript action execution in Alpine containers that are not on x64 Linux, where a
+  limited musl-compatibility workaround exists.
+
+  On ARM64 runners (ubuntu-24.04-arm, ubuntu-22.04-arm), the runner explicitly rejects
+  JavaScript actions run inside Alpine containers with this error. The check evaluates the
+  container image's /etc/os-release ID field: when ID=alpine is found AND the runner
+  architecture is not x64, the error is thrown.
+
+  Common trigger patterns:
+  - Workflow uses `container: alpine` or a custom image FROM alpine
+  - One or more steps use JavaScript-based actions (e.g. actions/upload-artifact,
+    actions/checkout, actions/setup-node)
+  - Workflow or matrix includes ubuntu-24.04-arm or ubuntu-22.04-arm runners
+
+  Upgrading to a larger ubuntu-based base image resolves the issue because glibc is
+  present. There is no planned fix to add ARM64 Alpine support to the runner.
+fix: |
+  Option 1 (recommended): Replace the Alpine container with a Debian/Ubuntu-based image.
+  Alpine is often chosen for image size, but if JavaScript actions must be used inside the
+  container, a glibc-based image is required on ARM64 runners.
+
+  Option 2: Run JavaScript actions as host-level steps (outside the container) and
+  restrict container use to run: shell steps that do not invoke JS actions.
+
+  Option 3: Restrict ARM64 runners to non-Alpine container images in your matrix.
+
+  Option 4: If the Alpine container is only for the build environment, restructure the
+  workflow so JavaScript actions (checkout, upload-artifact, etc.) run before the
+  container is started rather than inside it.
+fix_code:
+  - language: yaml
+    label: 'Replace Alpine with Debian-slim (smallest glibc image)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          container:
+            # Replace: image: alpine:latest
+            image: debian:bookworm-slim   # glibc-based, JS actions work on ARM64
+          steps:
+            - uses: actions/checkout@v6
+            - run: apt-get update && apt-get install -y curl
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Run JS actions on host, only use Alpine container for build steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          steps:
+            # Checkout on host (no container) — JS action works fine
+            - uses: actions/checkout@v6
+            # Run build inside Alpine via docker run (shell step, not JS action)
+            - name: Build in Alpine
+              run: |
+                docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work \
+                  alpine:latest sh -c "apk add --no-cache build-base && make"
+            # Upload on host — JS action works fine
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Matrix: restrict Alpine container to x64 runners only'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ matrix.runner }}
+          container:
+            image: ${{ matrix.runner == 'ubuntu-24.04-arm' && 'debian:bookworm-slim' || 'alpine:latest' }}
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm]
+          steps:
+            - uses: actions/checkout@v6
+
+prevention:
+  - 'Never use Alpine-based container images on ARM64 GitHub-hosted runners if any workflow step calls a JavaScript action'
+  - 'Use debian:bookworm-slim or ubuntu:24.04 as a lightweight glibc alternative to Alpine when JS actions must run in-container on ARM64'
+  - 'When migrating workflows to ARM64 runners, audit all container: image values for Alpine derivation (FROM alpine, alpine:latest, alpine:3.x)'
+  - 'Run JavaScript actions (checkout, upload-artifact, setup-*) as host-level steps before or after the Alpine container block when possible'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/739'
+    label: 'actions/upload-artifact#739 — JS Actions in Alpine containers not supported on ARM64 (Feb 2026)'
+  - 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: 'GitHub-hosted runners — ARM64 runner support'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'Running jobs in a container'

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

@@ -0,0 +1,96 @@
+id: runner-environment-188
+title: "macOS Self-Hosted Runner Concurrent Checkout Hangs — git-credential-osxkeychain Deadlock"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - self-hosted
+  - checkout
+  - concurrent
+  - osxkeychain
+  - credential
+  - hang
+patterns:
+  - regex: 'git-credential-osxkeychain store'
+    flags: i
+  - regex: 'run_command.*git-credential-osxkeychain'
+    flags: i
+error_messages:
+  - "trace: run_command: 'git credential-osxkeychain store'"
+  - "trace: exec: git-credential-osxkeychain store"
+  - "trace: start_command: /opt/homebrew/opt/git/libexec/git-core/git-credential-osxkeychain store"
+root_cause: |
+  When two or more concurrent jobs on the same macOS self-hosted runner both execute
+  `actions/checkout`, each job's git process attempts to acquire the macOS Keychain to store
+  the authentication token via `git-credential-osxkeychain`. Because the macOS Keychain
+  serializes write access, a second concurrent credential store call waits indefinitely for
+  the first to release the keychain lock — creating a deadlock that never resolves on its own.
+
+  The job hangs silently. The last visible log line is always the `git-credential-osxkeychain
+  store` trace, followed by no output until the 6-hour GitHub Actions job timeout cancels
+  the run. There is no error message — the step simply never completes.
+
+  Runner v2.331.0 (which moved the base macOS image to 26 / Tahoe) and checkout@v6 together
+  worsened the race condition frequency. The issue also affects earlier runner/checkout
+  version combinations when multiple jobs share the same macOS self-hosted runner workspace.
+fix: |
+  Two workarounds exist. The most reliable is a pre-checkout workspace cleanup step that
+  removes leftover lock files from prior concurrent runs. The second is disabling credential
+  persistence so git never calls the macOS Keychain at all.
+
+  Option A (most reliable — workspace cleanup before every checkout):
+    Add a step before `actions/checkout` that removes all workspace contents. This eliminates
+    stale `.git/index.lock`, `.git/gc.pid` and credential lock files that cause the hang.
+
+  Option B (simpler — disable credential persistence):
+    Set `persist-credentials: false` on the checkout step. This prevents git from calling
+    `git-credential-osxkeychain store` entirely since no token is persisted. Note: this
+    means subsequent git operations in the same job cannot use the persisted token, so you
+    must pass the token explicitly in each git call that needs it.
+
+  If the workspace directory itself is the issue (leftover `.git/index.lock`), add an explicit
+  pre-step that deletes `.git/index.lock` and `.git/gc.pid` if they exist.
+fix_code:
+  - language: yaml
+    label: "Option A — pre-checkout workspace cleanup (most reliable)"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - name: Clean workspace before checkout
+              run: |
+                find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+                  || echo "::warning::Workspace cleanup failed due to concurrent writes. Not fatal."
+            - uses: actions/checkout@v6
+  - language: yaml
+    label: "Option B — disable credential persistence to skip keychain"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - uses: actions/checkout@v6
+              with:
+                persist-credentials: false
+  - language: yaml
+    label: "Delete stale git lock files before checkout"
+    code: |
+      - name: Remove stale git lock files
+        run: |
+          rm -f "$GITHUB_WORKSPACE/.git/index.lock"
+          rm -f "$GITHUB_WORKSPACE/.git/gc.pid"
+      - uses: actions/checkout@v6
+prevention:
+  - "Use ephemeral self-hosted macOS runners (each job gets a fresh runner) to eliminate workspace state sharing between concurrent jobs"
+  - "Limit concurrency on the macOS runner's job queue to 1 using a concurrency group if ephemeral runners are not available"
+  - "Add a pre-checkout workspace cleanup step as a defensive measure on all macOS self-hosted runner jobs"
+  - "Set `persist-credentials: false` if downstream git operations do not require the persisted token"
+  - "Upgrade to the latest actions/checkout — version tags and runner versions interact; newer releases may reduce the deadlock window"
+docs:
+  - url: "https://stackoverflow.com/questions/79881327/github-actions-self-hosted-runner-on-macos-tries-to-checkout-repository-forever"
+    label: "Stack Overflow — macOS self-hosted runner checkout hangs forever (Feb 2026)"
+  - url: "https://github.com/actions/checkout/issues/550"
+    label: "actions/checkout#550 — Checkout gets stuck forever randomly on self-hosted runners"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs: About self-hosted runners"

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

@@ -0,0 +1,147 @@
+id: runner-environment-191
+title: 'GHCup 0.1.x → 0.2.x Upgrade on Ubuntu Runners Breaks Direct ghcup CLI Usage'
+category: runner-environment
+severity: error
+tags:
+  - haskell
+  - ghcup
+  - ubuntu-22.04
+  - ubuntu-24.04
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'ghcup: command not found'
+    flags: 'i'
+  - regex: 'ghcup list.*-r[0-9]+|version.*-r[0-9].*not found'
+    flags: 'i'
+  - regex: '\$HOME/\.ghcup/bin/ghc.*no such file|\.ghcup/bin/ghc.*not a regular file'
+    flags: 'i'
+  - regex: 'ghcup.*cabal install.*unknown command|cabal install.*unrecognized.*ghcup'
+    flags: 'i'
+error_messages:
+  - 'test -f ~/.ghcup/bin/ghc returned false (ghc not installed)'
+  - 'GHC version 9.6.6-r1 was not found in the expected location'
+  - 'Error: The value 9.6.6-r1 is not a valid GHC version'
+  - 'ghcup: error: no subcommand: cabal install'
+root_cause: |
+  The ubuntu-22.04 and ubuntu-24.04 runner image update released 2026-05-26
+  (ubuntu24/20260525.161.1, ubuntu22/20260525.156.1) upgraded the pre-installed GHCup
+  from 0.1.50.2 to 0.2.5.0. GHCup 0.2.x introduced several breaking CLI and
+  filesystem changes that affect workflows calling ghcup directly.
+
+  **Breaking changes in GHCup 0.2.x:**
+
+  1. **`ghcup list` version strings now include a `-rX` revision suffix** when a
+     revision update is available (e.g., `9.6.6-r1` instead of `9.6.6`). Scripts
+     that parse `ghcup list` output for version equality checks (e.g., `grep 9.6.6`)
+     or that pipe the version into other tools fail because of the unexpected suffix.
+
+  2. **`~/.ghcup/bin/` is now entirely composed of symlinks** (except the `ghcup`
+     binary itself). Previously, some binaries (like `ghc`, `cabal`, `hls`) were
+     hardlinks or regular executable files. Workflow steps using the POSIX file-
+     existence test `-f ~/.ghcup/bin/ghc` now return false because `-f` returns
+     false for symlinks. The check must be `-e` (exists) or `-L` (is symlink).
+
+  3. **Old undocumented subcommand alias removed**: `ghcup cabal install <ver>` as
+     an alternative form is gone. The canonical form `ghcup install cabal <ver>` and
+     `ghcup install ghc <ver>` still work. Workflows that copied old forum examples
+     using the deprecated form receive an "unknown subcommand" error.
+
+  4. **`ghcup compile hls --isolate=<dir>` changed output path**: binaries are now
+     installed into `<dir>/bin/` instead of `<dir>/`. Scripts expecting the binary
+     directly at the isolate path fail with "file not found".
+
+  Note: The `--install-targets` flag bug present in GHCup 0.2.0–0.2.2 was already
+  fixed before the runner images updated (runner ships 0.2.5.0). That specific bug
+  does not affect GitHub-hosted runners.
+fix: |
+  **For `-f` file existence checks** — replace with `-e` (any file type) or
+  `-L` (is symlink):
+
+  ```bash
+  # Before (breaks on GHCup 0.2.x):
+  if [ -f "$HOME/.ghcup/bin/ghc" ]; then ...
+
+  # After:
+  if [ -e "$HOME/.ghcup/bin/ghc" ]; then ...
+  ```
+
+  **For version parsing from `ghcup list`** — strip the revision suffix:
+
+  ```bash
+  GHC_VER=$(ghcup list -t ghc --show-criteria 'recommended' -r | awk '{print $2}' \
+    | sed 's/-r[0-9]*$//')
+  ```
+
+  Or use `--show-revisions=none` to suppress the suffix entirely:
+
+  ```bash
+  ghcup list -t ghc --show-revisions=none
+  ```
+
+  **For old subcommand syntax** — use the canonical form:
+
+  ```bash
+  # Before:
+  ghcup cabal install 3.12.1.0
+
+  # After:
+  ghcup install cabal 3.12.1.0
+  ```
+
+  **Best practice** — use `haskell-actions/setup` instead of calling ghcup
+  directly. The action is maintained to handle ghcup version changes:
+
+  ```yaml
+  - uses: haskell-actions/setup@v2
+    with:
+      ghc-version: '9.6.6'
+      cabal-version: 'latest'
+  ```
+fix_code:
+  - language: yaml
+    label: 'Use haskell-actions/setup instead of raw ghcup commands'
+    code: |
+      - name: Set up GHC
+        uses: haskell-actions/setup@v2
+        with:
+          ghc-version: '9.6.6'
+          cabal-version: 'latest'
+          enable-stack: false
+
+  - language: yaml
+    label: 'Conditional GHCup binary check — fix -f to -e'
+    code: |
+      - name: Check if GHC is available
+        run: |
+          # GHCup 0.2.x: all ~/.ghcup/bin/ entries are symlinks; use -e not -f
+          if [ -e "$HOME/.ghcup/bin/ghc" ]; then
+            echo "GHC found: $(ghc --version)"
+          else
+            ghcup install ghc recommended
+          fi
+
+  - language: yaml
+    label: 'Parse GHCup list output — strip revision suffix'
+    code: |
+      - name: Get recommended GHC version
+        run: |
+          # GHCup 0.2.x: version may include -rX revision suffix
+          GHC_VER=$(ghcup list -t ghc --show-revisions=none -r \
+            | grep 'recommended' | awk '{print $2}')
+          echo "GHC version: $GHC_VER"
+          ghcup install ghc "$GHC_VER"
+prevention:
+  - 'Use haskell-actions/setup instead of calling ghcup directly — it handles ghcup API changes across versions.'
+  - 'Use `-e` or `-L` for file existence checks on `~/.ghcup/bin/` entries, never `-f`.'
+  - 'Pin to specific GHC/Cabal versions in haskell-actions/setup rather than resolving "recommended" at runtime.'
+  - 'When parsing `ghcup list` output, use `--show-revisions=none` to suppress the `-rX` suffix added in 0.2.x.'
+docs:
+  - url: 'https://github.com/haskell/ghcup-hs/releases/tag/v0.2.1.0'
+    label: 'GHCup 0.2.1.0 release notes (breaking changes section)'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'Ubuntu 24.04 runner image release 20260525.161.1 — GHCup 0.1.50.2 → 0.2.5.0'
+  - url: 'https://github.com/actions/runner-images/issues/14142'
+    label: 'runner-images #14142 — GHCup 0.2 version banner format change'
+  - url: 'https://github.com/haskell/haskell-actions/tree/main/setup'
+    label: 'haskell-actions/setup — official Haskell CI setup action'

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

@@ -0,0 +1,144 @@
+id: runner-environment-192
+title: 'ubuntu-24.04 Kernel 6.17.0-1015-azure Oops in ublk_drv — User Block Device Workflows Hang'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - kernel
+  - ublk
+  - io-uring
+  - runner-image
+  - regression
+patterns:
+  - regex: 'ublk_init_queues.*Oops|RIP.*ublk_init_queues'
+    flags: 'i'
+  - regex: 'ublk_ctrl_add_dev|UBLK_U_CMD_ADD_DEV.*hang|ublk_drv.*kernel.*oops'
+    flags: 'i'
+  - regex: 'note: iou-wrk-.*exited with irqs disabled'
+    flags: 'i'
+  - regex: 'modprobe ublk_drv.*ublk.*add.*dev.*timeout|ublk.*command.*never completes'
+    flags: 'i'
+error_messages:
+  - 'RIP: 0010:ublk_init_queues+0x4e/0x1e0 [ublk_drv]'
+  - 'note: iou-wrk-* exited with irqs disabled'
+  - 'ublk_ctrl_add_dev+0x31a/0x5e0 [ublk_drv]'
+  - 'Oops: general protection fault, probably for non-canonical address'
+root_cause: |
+  The ubuntu-24.04 runner image released 2026-05-26 (version 20260525.161.1) ships
+  Linux kernel 6.17.0-1015-azure (upgraded from 6.17.0-1013-azure). This kernel
+  contains an upstream bug in the `ublk_drv` module: calling `UBLK_U_CMD_ADD_DEV`
+  once via io_uring triggers a kernel Oops in `ublk_init_queues+0x4e/0x1e0`.
+
+  **Affected call chain:**
+  ```
+  ublk_init_queues
+  ublk_ctrl_add_dev
+  ublk_ctrl_uring_cmd
+  io_uring_cmd
+  io_wq_submit_work
+  io_wq_worker
+  ```
+
+  After the Oops, the ADD_DEV io_uring command never receives a completion event
+  (CQE), so the userspace program waits indefinitely. The GitHub Actions job hangs
+  until it hits the workflow timeout.
+
+  **Affected environments:**
+  - ubuntu-24.04 amd64 hosted runners with kernel 6.17.0-1015-azure
+  - Any workflow that calls `modprobe ublk_drv` and then performs `UBLK_U_CMD_ADD_DEV`
+
+  **Unaffected environments:**
+  - ubuntu-22.04 runners (kernel 6.8.0-1052-azure — not affected)
+  - ubuntu-24.04 self-hosted runners still on kernel 6.17.0-1013-azure or earlier
+
+  This is an upstream `linux-azure` kernel bug (not a runner-images regression).
+  GitHub does not pin the kernel — it is delivered from Canonical's HWE channel.
+  A kernel SRU fix from Canonical will be picked up automatically in future
+  ubuntu-24.04 runner image releases.
+fix: |
+  **Workaround: pin ublk-based jobs to ubuntu-22.04 until the kernel SRU is deployed.**
+
+  ```yaml
+  ublk-test:
+    runs-on: ubuntu-22.04   # kernel 6.8.0 — ublk_drv works correctly
+    steps:
+      - uses: actions/checkout@v6
+      - run: |
+          sudo modprobe ublk_drv || {
+            sudo apt-get install -y --no-install-recommends \
+              "linux-modules-extra-$(uname -r)"
+            sudo modprobe ublk_drv
+          }
+          # your ublk test here
+  ```
+
+  **Alternative: install `linux-modules-extra` and test kernel version at runtime:**
+
+  ```bash
+  KERNEL=$(uname -r)
+  if [[ "$KERNEL" == "6.17.0-1015-azure" ]]; then
+    echo "::warning::Kernel 6.17.0-1015-azure has a ublk_drv bug. Skipping ublk tests."
+    exit 0
+  fi
+  ```
+
+  Track the upstream kernel SRU at Canonical:
+  https://bugs.launchpad.net/ubuntu/+source/linux-azure/
+fix_code:
+  - language: yaml
+    label: 'Pin ublk-dependent jobs to ubuntu-22.04 as workaround'
+    code: |
+      jobs:
+        ublk-integration:
+          # Workaround: ubuntu-24.04 kernel 6.17.0-1015-azure has a ublk_drv bug.
+          # Pin to ubuntu-22.04 until a fixed kernel SRU lands in ubuntu-24.04.
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v6
+            - name: Load ublk_drv
+              run: |
+                sudo modprobe ublk_drv || {
+                  sudo apt-get update -qq
+                  sudo apt-get install -y --no-install-recommends \
+                    "linux-modules-extra-$(uname -r)"
+                  sudo modprobe ublk_drv
+                }
+            - name: Run ublk tests
+              run: make test-ublk
+
+  - language: yaml
+    label: 'Matrix with runtime kernel guard to skip known-broken kernel'
+    code: |
+      jobs:
+        ublk-test:
+          strategy:
+            matrix:
+              runner: [ubuntu-22.04, ubuntu-24.04]
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v6
+            - name: Check kernel for ublk_drv bug
+              run: |
+                KERNEL=$(uname -r)
+                echo "Kernel: $KERNEL"
+                if [[ "$KERNEL" == "6.17.0-1015-azure" ]]; then
+                  echo "::warning::Skipping ublk tests on $KERNEL (known ublk_drv Oops)"
+                  echo "SKIP_UBLK=true" >> "$GITHUB_ENV"
+                fi
+            - name: Run ublk tests
+              if: env.SKIP_UBLK != 'true'
+              run: make test-ublk
+prevention:
+  - 'Monitor ubuntu-24.04 kernel version in release notes before running ublk/io_uring block device tests.'
+  - 'Add a kernel version gate in ublk-dependent CI steps to skip on known-bad kernels.'
+  - 'Subscribe to or monitor `actions/runner-images` issues for kernel regression reports on Ubuntu runners.'
+  - 'Consider pinning ublk integration tests to ubuntu-22.04 as a long-term stable baseline for kernel-intensive work.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14175'
+    label: 'runner-images #14175 — ubuntu-24.04 kernel 6.17.0-1015-azure Oops in ublk_drv (open)'
+  - url: 'https://github.com/e2b-dev/ublk-adddev-repro'
+    label: 'Minimal ublk UBLK_U_CMD_ADD_DEV repro repo'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'Ubuntu 24.04 runner image 20260525.161.1 — kernel 6.17.0-1015-azure'
+  - url: 'https://bugs.launchpad.net/ubuntu/+source/linux-azure/'
+    label: 'Canonical linux-azure bug tracker (for SRU status)'

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

@@ -0,0 +1,136 @@
+id: runner-environment-193
+title: 'ubuntu-24.04-arm64 GitHub-Managed Image Ships Ruby 3.2.3 vs x64 Ruby 4.0 — Matrix Builds Fail'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - arm64
+  - ruby
+  - matrix
+  - runner-image
+  - version-mismatch
+patterns:
+  - regex: 'Your Ruby version is 3\.2\.[0-9], but your Gemfile specified.*[~>].*4\.'
+    flags: 'i'
+  - regex: 'bundler.*RUBY_VERSION.*3\.2.*expected.*4\.|incompatible.*ruby.*3\.2.*4\.'
+    flags: 'i'
+  - regex: 'LoadError.*incompatible library version.*ruby.*3\.2|\.bundle.*built for Ruby 3\.2.*running.*4\.'
+    flags: 'i'
+  - regex: 'ubuntu-24\.04-arm.*ruby.*3\.2|arm64.*ruby.*version.*mismatch'
+    flags: 'i'
+error_messages:
+  - 'Your Ruby version is 3.2.3, but your Gemfile specified ~> 4.0'
+  - 'LoadError: incompatible library version - /path/to/native.bundle'
+  - "An error occurred while installing nokogiri (1.x.x), and Bundler cannot continue."
+  - 'Gem::RuntimeRequirementNotMetError: ruby 4.0 is required'
+root_cause: |
+  The first GitHub-managed Ubuntu 24.04 ARM64 runner image (ubuntu24-arm64/
+  20260531.15.1, released 2026-06-03) ships Ruby 3.2.3 as the default system Ruby.
+  In contrast, the Ubuntu 24.04 x86-64 runner image (ubuntu24/20260525.161.1) ships
+  Ruby 4.0.5. This version gap was introduced when GitHub took over ARM64 image
+  maintenance from Arm Limited in May–June 2026; the ARM64 image was rebuilt with a
+  different baseline software set.
+
+  **Affected workflows — any that run a Ruby matrix over both platforms:**
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-24.04, ubuntu-24.04-arm]
+  ```
+
+  Failure modes:
+  1. **Gemfile Ruby version constraint** — if the Gemfile (or `.ruby-version`) pins
+     `ruby ~> 4.0` (or uses Ruby 4.0 syntax features), the ARM64 run fails immediately
+     with "Your Ruby version is 3.2.3, but your Gemfile specified ~> 4.0".
+
+  2. **Native extension ABI mismatch** — if the workflow restores a gem cache built
+     on the x64 runner (Ruby 4.0 ABI), native extension `.bundle` files are
+     incompatible with Ruby 3.2 on ARM64, producing a `LoadError` at test time.
+
+  3. **Ruby 4.0 language/stdlib differences** — Ruby 4.0 removed several deprecated
+     methods that exist in Ruby 3.2 (e.g., Kernel#binding). Code that uses 4.0-only
+     APIs silently succeeds on x64 but may have unexpected behaviour differences on
+     ARM64.
+
+  4. **setup-ruby without an explicit ruby-version** — if no version is pinned, the
+     action resolves "system ruby" differently per platform, producing Ruby 3.2 on
+     ARM64 and Ruby 4.0 on x64.
+
+  Ubuntu ARM64 runners maintained by Arm Limited previously matched x64 Ruby
+  versions more closely. The GitHub-managed ARM64 baseline is younger and will
+  converge with x64 over subsequent image releases.
+fix: |
+  **Explicit Ruby version with ruby/setup-ruby** on all platforms to override the
+  system Ruby and get a consistent version:
+
+  ```yaml
+  - uses: ruby/setup-ruby@v1
+    with:
+      ruby-version: '3.3'   # or whatever version your project supports on both arches
+      bundler-cache: true
+  ```
+
+  **Separate cache keys per OS/arch** to avoid cross-ABI gem cache poisoning:
+
+  ```yaml
+  - uses: actions/cache@v4
+    with:
+      path: vendor/bundle
+      key: ${{ runner.os }}-${{ runner.arch }}-ruby-${{ hashFiles('Gemfile.lock') }}
+  ```
+
+  **Guard Gemfile ruby version** to accept both 3.x and 4.x on the arm64 matrix:
+
+  ```ruby
+  # Gemfile
+  ruby '>= 3.2'   # instead of ~> 4.0, to allow both ubuntu-24.04 and ubuntu-24.04-arm
+  ```
+fix_code:
+  - language: yaml
+    label: 'Pin Ruby version with setup-ruby across all matrix platforms'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-24.04, ubuntu-24.04-arm]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v6
+
+            # Explicitly pin Ruby to get the same version on x64 AND ARM64.
+            # Without this, x64 gets Ruby 4.0.x and ARM64 gets Ruby 3.2.x.
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'    # consistent across both architectures
+                bundler-cache: true
+
+            - run: bundle exec rspec
+
+  - language: yaml
+    label: 'Per-arch gem cache key to prevent ABI mismatch on cache restore'
+    code: |
+      - name: Cache gems
+        uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          # Include runner.arch so ARM64 and x64 don't share native extension builds
+          key: >-
+            ${{ runner.os }}-${{ runner.arch }}-gems-
+            ${{ hashFiles('Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-gems-
+prevention:
+  - 'Always use `ruby/setup-ruby` with an explicit `ruby-version` in cross-arch matrix jobs — never rely on the system Ruby.'
+  - 'Include `runner.arch` in gem cache keys to prevent native extension ABI mismatches between x64 and ARM64 runs.'
+  - 'Set Gemfile Ruby version constraint to `>= 3.2` instead of `~> 4.0` when the matrix includes ubuntu-24.04-arm.'
+  - 'Check the ubuntu24-arm64 runner release notes for software version differences vs ubuntu-24.04 x64 before adding ARM64 to your CI matrix.'
+docs:
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24-arm64%2F20260531.15'
+    label: 'ubuntu24-arm64/20260531.15 — first GitHub-managed ARM64 image (Ruby 3.2.3)'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'ubuntu24/20260525.161.1 — Ubuntu 24.04 x64 image (Ruby 4.0.5)'
+  - url: 'https://github.com/actions/runner-images/issues/14100'
+    label: 'runner-images #14100 — ARM64 runner images now maintained by GitHub'
+  - url: 'https://github.com/ruby/setup-ruby'
+    label: 'ruby/setup-ruby — install a consistent Ruby version on any runner'