@htekdev/actions-debugger 1.0.32 → 1.0.34

package/errors/known-unsolved/bulk-tag-push-over-three-silent-drop.yml

@@ -0,0 +1,115 @@
+id: 'known-unsolved-031'
+title: 'Pushing more than 3 tags simultaneously silently drops workflow runs for excess tags — GitHub platform limit'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - push
+  - tags
+  - bulk-push
+  - webhook
+  - workflow-trigger
+  - limitation
+  - monorepo
+patterns:
+  - regex: 'push\s+--tags'
+    flags: 'i'
+  - regex: 'on:\s*\n\s*push:\s*\n\s*tags:'
+    flags: 'im'
+error_messages:
+  - 'No workflow runs created for some tags in bulk tag push'
+root_cause: |
+  GitHub's webhook delivery system has a documented hard limit: when more than 3 tags
+  are pushed simultaneously in a single push operation, push webhook events are only
+  created for the first 3 matching tags. Workflows for the remaining tags are silently
+  never triggered — no warning, no error, no failed run.
+
+  From the GitHub webhook events and payloads documentation:
+  "Events will not be created for tags when more than three tags are pushed at once."
+  (A similar limit of 5000 applies to branch pushes in a single operation, making the
+  3-tag threshold unexpectedly low by comparison.)
+
+  This is a platform-level constraint with no opt-out or configuration setting.
+
+  Common use cases affected:
+  - Monorepo release pipelines that tag multiple packages simultaneously
+    (e.g., package-a/v1.2.0, package-b/v1.0.0, package-c/v2.0.0, package-d/v0.5.0)
+  - Automated tooling that creates and pushes several version tags in one batch
+  - Release scripts using bulk push operations after creating several release tags
+  - Any CI pipeline where batch tagging is a normal part of the release flow
+
+  Source: actions/runner#3644 (7 reactions, Jan 2025, open), GitHub Docs push event.
+fix: |
+  No native fix — the 3-tag limit is a GitHub platform constraint. Workarounds:
+
+  Option 1: Push tags individually one at a time in a loop (slower but reliable).
+
+  Option 2: After a bulk tag operation, use the GitHub CLI to manually trigger
+  workflows for the tags that were silently skipped:
+    gh workflow run release.yml --ref tag-name
+
+  Option 3 (recommended for monorepos): Switch from push:tags triggered workflows to
+  repository_dispatch triggered release workflows. Use a coordination script that
+  pushes tags and then dispatches one workflow event per tag. This removes the
+  3-tag webhook constraint entirely.
+
+  Option 4: Use workflow_dispatch with a tag name input parameter and invoke it once
+  per tag from a release coordination script.
+fix_code:
+  - language: yaml
+    label: 'repository_dispatch-based release trigger bypassing the 3-tag limit'
+    code: |
+      # Release coordination script (run in CI or locally):
+      #
+      # For each tag you want to release, dispatch a repository_dispatch event:
+      #
+      #   for tag in package-a/v1.2.0 package-b/v1.0.0 package-c/v2.0.0; do
+      #     gh api repos/{owner}/{repo}/dispatches \
+      #       --field event_type=release \
+      #       --field "client_payload[tag]=$tag"
+      #   done
+
+      # Workflow triggered per tag via repository_dispatch:
+      on:
+        repository_dispatch:
+          types: [release]
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.client_payload.tag }}
+
+            - name: Build and publish
+              run: |
+                echo "Releasing ${{ github.event.client_payload.tag }}"
+                # add actual release steps here
+  - language: yaml
+    label: 'workflow_dispatch with tag input — invoke once per tag from release script'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            tag:
+              description: 'Tag to release (e.g. package-a/v1.2.0)'
+              required: true
+              type: string
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ inputs.tag }}
+            - run: echo "Releasing ${{ inputs.tag }}"
+prevention:
+  - 'Never rely on bulk push operations to trigger per-tag workflows in monorepos — push tags individually or use repository_dispatch/workflow_dispatch patterns'
+  - 'Audit your release pipeline: if bulk tag operations are used and more than 3 tags are pushed at once, some workflow runs are silently missing'
+  - 'Add a post-release verification step that confirms a workflow run exists for each expected tag, alerting if any are missing'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#push'
+    label: 'GitHub Docs: push webhook — 3-tag limit for simultaneous bulk tag pushes'
+  - url: 'https://github.com/actions/runner/issues/3644'
+    label: 'actions/runner#3644: Workflow fails to trigger on multiple tags push simultaneously (Jan 2025, open)'

package/errors/runner-environment/checkout-detached-head-git-push-fail.yml

@@ -0,0 +1,104 @@
+id: 'runner-environment-089'
+title: '`actions/checkout` leaves repository in detached HEAD state — subsequent `push` operations fail with "You are not currently on a branch"'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - detached-head
+  - push
+  - pull-request
+  - branch
+  - git-operations
+patterns:
+  - regex: 'fatal: You are not currently on a branch\.'
+    flags: 'i'
+  - regex: 'To push the history leading to the current \(detached HEAD\)'
+    flags: 'i'
+  - regex: 'detached HEAD.*\d+\].*fatal'
+    flags: 'i'
+error_messages:
+  - 'fatal: You are not currently on a branch.'
+  - 'To push the history leading to the current (detached HEAD) state now, use'
+  - '    git push origin HEAD:<name-of-remote-branch>'
+  - 'Process completed with exit code 128.'
+root_cause: |
+  actions/checkout performs a detached HEAD checkout by default for pull_request events.
+  For pull_request triggers, GitHub provides a synthetic merge ref
+  (refs/pull/N/merge) rather than a real branch ref, so the action checks out
+  this merge commit without creating or tracking a local branch.
+
+  When subsequent workflow steps attempt to commit and push changes back to the
+  repository — for example, auto-formatting, documentation builds, coverage report
+  generation, or generated file updates — the operation fails because no remote
+  branch can be determined from a detached HEAD state.
+
+  This affects any workflow step that:
+  - Runs push operations after making commits in the workflow
+  - Uses tools that internally run push operations (e.g., auto-commit, changelog tools,
+    version bumpers)
+  - Expects to push back to the PR branch after making modifications
+
+  On push events, the checkout is also detached if ref: is not specified with the
+  branch name, because the default ref is github.sha (a commit SHA, not a branch name).
+
+  Tracked: actions/checkout#317 (44 reactions, ongoing since 2020, still receiving
+  comments in 2025).
+fix: |
+  Specify ref: in the checkout step to check out the branch name rather than a
+  commit SHA or merge ref. Once on a named branch, push-back operations work normally.
+
+  For pull_request events: use github.event.pull_request.head.ref
+  For push events: use github.ref_name (available since Runner 2.294.0)
+  For workflows triggered by multiple event types: branch the ref selection by
+  event name as shown in the third example below.
+fix_code:
+  - language: yaml
+    label: 'Fix for pull_request-triggered workflows that push back to the PR branch'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Check out the actual PR branch, not the detached merge ref
+                ref: ${{ github.event.pull_request.head.ref }}
+  - language: yaml
+    label: 'Fix for push-triggered workflows that commit and push back'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Checks out the branch name (e.g. main) instead of the commit SHA
+                ref: ${{ github.ref_name }}
+  - language: yaml
+    label: 'Universal fix for workflows triggered by multiple event types'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout (pull_request)
+              if: github.event_name == 'pull_request'
+              uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.ref }}
+
+            - name: Checkout (push or workflow_dispatch)
+              if: github.event_name != 'pull_request'
+              uses: actions/checkout@v4
+              with:
+                ref: ${{ github.ref_name }}
+prevention:
+  - 'Always specify ref: in checkout steps for workflows that push changes back to the repository'
+  - 'Use github.ref_name (not github.sha) for push-triggered workflows to get the branch name rather than a detached commit SHA'
+  - 'Test push-back workflows on both pull_request and push triggers to detect detached HEAD issues before they reach production'
+  - 'If using actions/checkout@v4, prefer explicit ref: values over relying on defaults when the workflow modifies and pushes files'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/317'
+    label: 'actions/checkout#317: fatal: You are not currently on a branch (44 reactions, 2020–2025)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'GitHub Docs: pull_request event — uses synthetic merge ref by default'

package/errors/runner-environment/macos-15-arm64-homebrew-rustup-init-argv-rejected.yml

@@ -0,0 +1,114 @@
+id: 'runner-environment-086'
+title: 'macOS 15 arm64 Homebrew `rustup-init` rejects `+stable` toolchain specifier and subcommands — Rust builds fail with ~50% probability'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - arm64
+  - homebrew
+  - rust
+  - rustup
+  - maturin
+  - napi-rs
+  - image-regression
+patterns:
+  - regex: 'error: unexpected argument .+stable. found'
+    flags: 'i'
+  - regex: 'error: unexpected argument .metadata. found'
+    flags: 'i'
+  - regex: 'Usage: rustup-init\[EXE\] \[OPTIONS\]'
+    flags: 'i'
+  - regex: 'macos-15-arm64.*20260511'
+    flags: 'i'
+error_messages:
+  - "Error: error: error: unexpected argument '+stable' found"
+  - "error: error: unexpected argument 'metadata' found"
+  - "Usage: rustup-init[EXE] [OPTIONS]"
+  - "info: self-update is disabled for this build of rustup"
+  - "Could not parse the Cargo.toml: Error: Command failed: cargo metadata"
+root_cause: |
+  The macos-15-arm64 runner image version 20260511.0048 ships a broken Homebrew rustup
+  formula at /opt/homebrew/bin/rustup (version 1.29.0) whose bundled rustup-init binary
+  rejects standard argv that the outer rustup CLI forwards internally.
+
+  When rustup receives a command like `rustup component add llvm-tools-preview` or when
+  cargo shims invoke `cargo metadata`, the outer rustup binary calls rustup-init with
+  forwarded arguments (+stable, metadata, etc.). On this image version, rustup-init
+  treats these as unknown positional arguments and immediately exits with an error.
+
+  The failure is intermittent because GitHub's runner scheduler assigns jobs to different
+  image versions: 20260511.0048 (broken) and 20260427.0018 (working). A single workflow
+  run with multiple matrix entries can produce a mix of passing and failing jobs depending
+  on which image version each job lands on. Reruns do not reliably fix the issue because
+  rerun jobs may again be scheduled on the broken image version.
+
+  Affected downstream tools (all work on 20260427.0018, all fail on 20260511.0048):
+  - PyO3/maturin-action@v1 — calls `rustup component add llvm-tools-preview`
+  - @napi-rs/cli — calls `cargo metadata --format-version 1`
+  - Any workflow that calls `rustup component add` with a toolchain specifier
+  - Any Rust build that uses the Homebrew rustup shim for internal rustup-init calls
+
+  Tracked in actions/runner-images#14097 (May 2026, open).
+fix: |
+  Option 1 (recommended): Install rustup from the upstream installer (sh.rustup.rs)
+  before any Rust build steps. This replaces the broken Homebrew binary at
+  /opt/homebrew/bin/rustup with the upstream version and resolves the argv issue.
+
+  Option 2: Pin the runner to macos-15-arm64 explicitly and avoid the image lottery.
+  Note: this only temporarily avoids the issue; broken images will eventually be the
+  only version served.
+
+  Option 3: Use the dtolnay/rust-toolchain action before any Rust operations to
+  install or update rustup via the upstream installer, bypassing the Homebrew version.
+fix_code:
+  - language: yaml
+    label: 'Replace Homebrew rustup with upstream installer before Rust build steps'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # or macos-15-arm64
+          steps:
+            - uses: actions/checkout@v6
+
+            - name: Replace Homebrew rustup with upstream installer
+              run: |
+                # Remove Homebrew rustup to avoid the broken rustup-init binary
+                brew uninstall rustup-init rustup 2>/dev/null || true
+                # Install from upstream — stable, no Homebrew dependency
+                curl https://sh.rustup.rs -sSf | sh -s -- -y --no-modify-path
+                echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+            - name: Install Rust target
+              run: rustup target add aarch64-apple-darwin
+
+            - uses: PyO3/maturin-action@v1
+              with:
+                target: aarch64-apple-darwin
+  - language: yaml
+    label: 'Use dtolnay/rust-toolchain to install a clean rustup before builds'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v6
+
+            - name: Install Rust toolchain (upstream, not Homebrew)
+              uses: dtolnay/rust-toolchain@stable
+              with:
+                components: llvm-tools-preview
+
+            - name: Build
+              run: cargo build --release
+prevention:
+  - 'Prefer dtolnay/rust-toolchain or rustup-toolchain-install-master for cross-platform Rust toolchain management rather than relying on the pre-installed Homebrew rustup'
+  - 'Test macOS ARM64 jobs on both arm64 and x86-via-Rosetta matrix entries to detect image-lottery regressions early'
+  - 'Watch actions/runner-images#14097 for the fix and the image version that resolves the broken rustup-init'
+  - 'Avoid using the Homebrew rustup binary directly; upstream rustup at ~/.cargo/bin/rustup is more stable across image updates'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14097'
+    label: 'actions/runner-images#14097: macos-15-arm64/20260511.0048 ships broken Homebrew rustup-init (May 2026)'
+  - url: 'https://rustup.rs/'
+    label: 'rustup.rs: Official upstream rustup installer'
+  - url: 'https://github.com/PyO3/maturin-action'
+    label: 'PyO3/maturin-action: Affected action that calls rustup component add'

package/errors/runner-environment/ubuntu-24-04-iproute2-kernel-614-vxlan-segfault.yml

@@ -0,0 +1,102 @@
+id: 'runner-environment-087'
+title: '`ip -d link show` segfaults (exit 139 / SIGSEGV) on VXLAN interfaces on ubuntu-24.04 after kernel 6.14 upgrade'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24-04
+  - networking
+  - vxlan
+  - iproute2
+  - kernel
+  - segfault
+  - regression
+  - container-networking
+patterns:
+  - regex: 'Segmentation fault.*ip.*link'
+    flags: 'i'
+  - regex: 'ip -d link show.*exit.*139'
+    flags: 'i'
+  - regex: 'ip\s+-d\s+link\s+show'
+    flags: 'i'
+error_messages:
+  - 'Segmentation fault (core dumped)'
+  - 'Process completed with exit code 139.'
+  - 'ip: Segmentation fault'
+root_cause: |
+  On ubuntu-24.04 runner image 20260209.23 and later, the kernel was upgraded to
+  6.14.0-1017-azure while the iproute2 package remained at version 6.1.0-1ubuntu6.2.
+
+  Linux kernel 6.14 introduced a new VXLAN netlink attribute (IFLA_VXLAN_FAN_MAP) in
+  the rtnetlink interface. When iproute2 6.1 receives a netlink response containing this
+  unrecognized attribute and parses it with the -d (details) flag, it dereferences an
+  unexpected attribute structure, triggering a SIGSEGV.
+
+  The crash occurs specifically when:
+  1. A VXLAN network interface exists on the runner (e.g., created with `ip link add ... type vxlan`)
+  2. `ip -d link show dev <vxlan-interface>` is executed to inspect its details
+
+  Without the -d flag, `ip link show` succeeds. The regression was confirmed by comparing:
+  - Working image: 20260201.15.1 (kernel 6.11.0-1018-azure, iproute2 6.1.0-1ubuntu6.2)
+  - Broken image:  20260209.23.1 (kernel 6.14.0-1017-azure, iproute2 6.1.0-1ubuntu6.2)
+
+  Affected workflows: any CI that creates VXLAN interfaces for network simulation, overlay
+  networking tests, or Kubernetes-in-CI scenarios (e.g., containerlab, kind with custom
+  network topologies, network protocol testing).
+
+  Tracked in actions/runner-images#13669 (February 2026, open).
+fix: |
+  Option 1: Upgrade iproute2 to a version compatible with kernel 6.14 at the start of
+  the job. Install a newer iproute2 from a backport PPA or compile from source.
+
+  Option 2: Avoid the -d flag when only basic VXLAN interface information is needed.
+  `ip link show dev <vxlan-interface>` (without -d) does not trigger the crash.
+
+  Option 3: Pin to ubuntu-22.04, which uses an older kernel/iproute2 combination that
+  does not exhibit this issue.
+
+  Option 4: Parse VXLAN interface details via /sys/class/net/ sysfs entries instead of
+  relying on `ip -d link show`.
+fix_code:
+  - language: yaml
+    label: 'Upgrade iproute2 before creating VXLAN interfaces to avoid segfault'
+    code: |
+      jobs:
+        network-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Upgrade iproute2 to kernel-6.14-compatible version
+              run: |
+                sudo apt-get update -qq
+                sudo apt-get install -y --only-upgrade iproute2
+                ip -V    # Verify new version
+
+            - name: Create and inspect VXLAN interface
+              run: |
+                sudo ip link add vxlan-test type vxlan id 100 \
+                  local 10.0.0.1 remote 10.0.0.2 dev eth0 dstport 4789
+                ip -d link show dev vxlan-test   # Safe with upgraded iproute2
+
+  - language: yaml
+    label: 'Avoid -d flag as workaround on ubuntu-24.04 without iproute2 upgrade'
+    code: |
+      jobs:
+        network-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Create VXLAN interface
+              run: |
+                sudo ip link add vxlan-test type vxlan id 100 dstport 4789
+                # Use ip link show WITHOUT -d flag to avoid SIGSEGV on kernel 6.14
+                ip link show dev vxlan-test
+                # VXLAN-specific attributes via sysfs instead of iproute2 -d output:
+                cat /sys/class/net/vxlan-test/carrier || true
+prevention:
+  - 'Add an iproute2 upgrade step when workflows inspect VXLAN or other advanced interface types with `ip -d link show`'
+  - 'Watch actions/runner-images#13669 for a fix that aligns iproute2 with the kernel 6.14 netlink attributes'
+  - 'Test network-intensive CI on both ubuntu-22.04 and ubuntu-24.04 to detect kernel/iproute2 mismatch regressions'
+  - 'Consider ubuntu-22.04 for VXLAN-dependent workflows until the iproute2 package is updated on ubuntu-24.04 images'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13669'
+    label: 'actions/runner-images#13669: ip -d link show segfaults on vxlan interfaces — iproute2/kernel 6.14 mismatch'
+  - url: 'https://manpages.ubuntu.com/manpages/noble/man8/ip-link.8.html'
+    label: 'Ubuntu ip-link manpage: ip link show options'

package/errors/runner-environment/ubuntu-slim-setup-node-semver-range-toolcache-miss.yml

@@ -0,0 +1,108 @@
+id: 'runner-environment-088'
+title: '`ubuntu-slim` runner has empty Node.js toolcache — `setup-node` with semver range downloads latest patch instead of using cached version'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-slim
+  - setup-node
+  - toolcache
+  - semver
+  - caching
+  - node
+  - version-mismatch
+patterns:
+  - regex: 'evaluating 0 versions'
+    flags: 'i'
+  - regex: 'Attempting to download.*\.\.\.'
+    flags: 'i'
+  - regex: 'ubuntu-slim.*setup-node'
+    flags: 'i'
+error_messages:
+  - '##[debug]evaluating 0 versions'
+  - '##[debug]match not found'
+  - 'Attempting to download 24.x...'
+  - 'Acquiring 24.13.1 - x64 from https://github.com/actions/node-versions/releases/download/'
+root_cause: |
+  The ubuntu-slim runner image ships with an empty or absent Node.js toolcache manifest.
+  When actions/setup-node evaluates a semver range (e.g., 24, 24.x, 22.x) it first
+  inspects the local toolcache versions manifest. On ubuntu-slim, the manifest contains
+  zero cached versions (log line: "evaluating 0 versions"), so setup-node falls through
+  to download the latest matching version from GitHub releases at runtime.
+
+  On ubuntu-24.04 and ubuntu-latest, setup-node finds the cached version (e.g., 24.13.0)
+  and logs "Found tool in cache". The same workflow on ubuntu-slim downloads a newer
+  patch release (e.g., 24.13.1) because the remote versions API returns the freshest
+  available release.
+
+  This causes three distinct problems:
+  1. Slower CI: every job downloads Node.js from the network instead of using the cache
+  2. Version drift: ubuntu-slim jobs may use a different Node.js version than ubuntu-24.04
+     jobs in the same matrix, silently breaking cross-platform consistency checks
+  3. Test failures: libraries that cache built binaries keyed on Node.js version will
+     produce cache misses across ubuntu-slim and ubuntu-latest jobs in the same run
+
+  Reproduced on ubuntu-slim image version 20260120.46.1.
+  Tracked in actions/runner-images#13671 and actions/setup-node#1492 (February 2026).
+fix: |
+  Option 1: Pin an explicit Node.js version (e.g., 24.13.0) instead of a semver range.
+  setup-node downloads this version on ubuntu-slim, but the result is deterministic and
+  matches any version you also pin on ubuntu-latest or ubuntu-24.04.
+
+  Option 2: Use a .node-version or .nvmrc file with an exact version. setup-node reads
+  the file and pins to that version on all runner images.
+
+  Option 3: Use actions/cache to manually cache the Node.js installation directory on
+  ubuntu-slim jobs.
+
+  Option 4: Avoid ubuntu-slim for workflows that require a specific Node.js toolcache
+  version. Use ubuntu-24.04 or ubuntu-latest which ship pre-cached Node.js versions.
+fix_code:
+  - language: yaml
+    label: 'Pin exact Node.js version to avoid toolcache miss on ubuntu-slim'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-slim   # empty toolcache
+          steps:
+            - uses: actions/checkout@v6
+
+            # WRONG: semver range downloads latest patch on ubuntu-slim
+            # - uses: actions/setup-node@v6
+            #   with:
+            #     node-version: '24'    # evaluating 0 versions → downloads 24.13.1
+
+            # CORRECT: explicit version is deterministic on all images
+            - uses: actions/setup-node@v6
+              with:
+                node-version: '24.13.0'   # exact — no toolcache lookup needed
+
+  - language: yaml
+    label: 'Use .node-version file for consistent version across all runner images'
+    code: |
+      # .node-version (at repo root):
+      #   24.13.0
+
+      jobs:
+        build:
+          runs-on: ${{ matrix.os }}
+          strategy:
+            matrix:
+              os: [ubuntu-slim, ubuntu-24.04, macos-latest]
+          steps:
+            - uses: actions/checkout@v6
+
+            - uses: actions/setup-node@v6
+              with:
+                node-version-file: '.node-version'   # same version on all images
+prevention:
+  - 'Use exact Node.js versions (not semver ranges like 24.x) when running on ubuntu-slim to ensure deterministic toolcache behavior'
+  - 'Add a .node-version or .nvmrc file at the repo root and reference it with node-version-file: for consistent versions across all runner images'
+  - 'In matrix builds mixing ubuntu-slim with ubuntu-24.04, verify that node --version outputs match to detect silent version drift'
+  - 'Watch actions/runner-images#13671 for a fix that pre-populates the ubuntu-slim toolcache with a Node.js manifest'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13671'
+    label: 'actions/runner-images#13671: setup-node incorrectly downloads latest on ubuntu-slim'
+  - url: 'https://github.com/actions/setup-node/issues/1492'
+    label: 'actions/setup-node#1492: ubuntu-slim toolcache manifest missing'
+  - url: 'https://github.com/actions/setup-node#usage'
+    label: 'actions/setup-node documentation: node-version-file option'

package/errors/silent-failures/cache-restore-fail-on-cache-miss-silent-bug.yml

@@ -0,0 +1,115 @@
+id: 'silent-failures-040'
+title: '`actions/cache/restore` `fail-on-cache-miss: true` silently does not halt the workflow in v3.3.2–v3.3.3 — subsequent steps execute despite cache miss'
+category: silent-failures
+severity: silent-failure
+tags:
+  - cache
+  - fail-on-cache-miss
+  - cache-restore
+  - silent-failure
+  - regression
+  - cache-v3
+  - cache-v4
+patterns:
+  - regex: 'Failed to restore cache entry\. Exiting as fail-on-cache-miss is set\.'
+    flags: 'i'
+  - regex: 'fail-on-cache-miss.*true'
+    flags: 'i'
+error_messages:
+  - 'Error: Failed to restore cache entry. Exiting as fail-on-cache-miss is set.'
+  - 'Warning: Cache not found for keys:'
+root_cause: |
+  actions/cache@v3.3.2 and v3.3.3 contain a bug in the actions/cache/restore sub-action
+  where fail-on-cache-miss: true does not actually halt the workflow when no cache entry
+  is found.
+
+  The bug has two components (tracked in PR#1327):
+
+  1. Logic error: restoreImpl.ts initializes earlyExit to undefined (falsy) regardless
+     of whether fail-on-cache-miss is set. The conditional `if (earlyExit)` check always
+     evaluates to false, so process.exit(1) is never called on a miss.
+
+  2. Exit code conflict: even when process.exit(1) is called, it overwrites the exit
+     code previously set by core.setFailed(), causing the runner to record the step
+     outcome as 'success' despite the logged error message.
+
+  Observable behavior in affected versions:
+  - The step log shows: "Error: Failed to restore cache entry. Exiting as
+    fail-on-cache-miss is set."
+  - The step is marked with a red X in the UI but step.outcome is 'success'
+  - All subsequent steps execute normally as if no error occurred
+  - Jobs that should have stopped at the cache guard proceed to completion
+
+  This silently undermines workflows that use fail-on-cache-miss to enforce a
+  warm-cache-required pattern (e.g., a build artifact must exist from a prior job).
+
+  Fixed in: actions/cache@v3.3.4 and actions/cache@v4.0.2+ via PR#1327 (merged March 2024).
+  Affected: actions/cache@v3.3.2, v3.3.3 and the corresponding actions/cache/restore versions.
+
+  Source: actions/cache#1265 (11 reactions), actions/cache PR#1327 (merged March 2024).
+fix: |
+  Option 1 (recommended): Update to actions/cache@v4 (v4.0.2+) or actions/cache@v3.3.4+
+  where the earlyExit logic and exit code handling are corrected.
+
+  Option 2: Roll back to actions/cache@v3.3.1 — the last version before the regression
+  was introduced.
+
+  Option 3 (belt-and-suspenders, any version): Add an explicit guard step after the
+  restore that checks the cache-hit output and exits manually. This works regardless
+  of the action version and is the most robust approach.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to fixed actions/cache version (v3.3.4+ or v4.0.2+)'
+    code: |
+      jobs:
+        downstream:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # v4.0.2+ correctly fails the step AND stops the job on cache miss
+            - name: Restore build artifacts
+              uses: actions/cache/restore@v4
+              with:
+                path: dist/
+                key: build-${{ github.sha }}
+                fail-on-cache-miss: true
+
+            - name: Run tests against build
+              run: make test-dist
+  - language: yaml
+    label: 'Belt-and-suspenders explicit guard (works on all cache versions)'
+    code: |
+      jobs:
+        downstream:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore build artifacts
+              id: cache-restore
+              uses: actions/cache/restore@v4
+              with:
+                path: dist/
+                key: build-${{ github.sha }}
+                fail-on-cache-miss: false   # Do not rely on this alone
+
+            - name: Abort if build cache missing
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              run: |
+                echo "::error::Build artifacts not found in cache — run the build job first."
+                exit 1
+
+            - name: Run tests against build
+              run: make test-dist
+prevention:
+  - 'Pin actions/cache and actions/cache/restore to v3.3.4+ or v4.0.2+ when using fail-on-cache-miss'
+  - 'Add an explicit guard step checking steps.ID.outputs.cache-hit alongside fail-on-cache-miss for critical cache gates'
+  - 'Verify that a failed cache restore truly stops downstream steps by running a workflow with a known cache miss before relying on fail-on-cache-miss in production'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1265'
+    label: 'actions/cache#1265: fail-on-cache-miss not failing the workflow (11 reactions, Oct 2023)'
+  - url: 'https://github.com/actions/cache/pull/1327'
+    label: 'actions/cache PR#1327: Fix fail-on-cache-miss not working (merged March 2024)'

package/errors/silent-failures/step-summary-content-silently-dropped-near-limit.yml

@@ -0,0 +1,115 @@
+id: 'silent-failures-039'
+title: '`GITHUB_STEP_SUMMARY` content silently discarded when write size approaches the 1 MiB per-step limit'
+category: silent-failures
+severity: silent-failure
+tags:
+  - step-summary
+  - github-step-summary
+  - silent-discard
+  - 1mib-limit
+  - job-summary
+  - reporting
+patterns:
+  - regex: 'GITHUB_STEP_SUMMARY'
+    flags: 'i'
+  - regex: '\$env:GITHUB_STEP_SUMMARY'
+    flags: 'i'
+error_messages:
+  - 'Summary content written to /home/runner/work/_temp/_github_workflow/step_summary_*.md'
+  - 'Summary content written to C:\Users\runneradmin\AppData\Local\Temp\_github_workflow\step_summary_*.md'
+root_cause: |
+  The GitHub Actions runner enforces a 1 MiB (1,048,576 bytes) per-step size limit on
+  GITHUB_STEP_SUMMARY content. When a step writes content that is within approximately
+  2 bytes of this limit, the runner silently discards the entire summary with no error
+  message, no warning, and no non-zero exit code.
+
+  Two distinct bugs are present (both observed on runner 2.333.1+):
+
+  Bug 1 — Off-by-one at the limit boundary: Content that is exactly (1 MiB - 1) bytes
+  is rejected as "too long" even though it is one byte below the documented limit.
+  The effective hard limit is (1 MiB - 2) bytes, not 1 MiB.
+
+  Bug 2 — Silent discard near the boundary: Content written when the running total is
+  within ~2 bytes of the effective limit is silently dropped. The write succeeds (no
+  error), the step exits 0, but the summary does not appear in the GitHub Actions UI.
+  There is no log line, annotation, or job-level error indicating the drop occurred.
+
+  This is particularly dangerous for CI workflows that rely on step summary for:
+  - Test result tables (many failed tests → large HTML tables)
+  - Build logs written to summary for easy access
+  - Deployment manifests or diff outputs
+  - Security scan results
+
+  The content is lost at job execution time; there is no way to recover it after the fact.
+  The only indication is that the summary section in the GitHub UI appears blank or shows
+  less content than expected.
+
+  Tracked in actions/runner#4337 (April 2026, open).
+fix: |
+  Truncate summary content to a safe size before writing to GITHUB_STEP_SUMMARY.
+  Leave a margin of ~5 KB below the 1 MiB limit to account for multi-step accumulation
+  and the off-by-one bug.
+
+  For multi-step workflows, track cumulative size: each step's contribution adds to the
+  total step summary for the job. The 1 MiB limit applies per step, not per job.
+
+  Always validate that critical summary content was written by checking the file size
+  after the write, not by relying on exit code alone.
+fix_code:
+  - language: yaml
+    label: 'Truncate step summary to safe size before writing (bash)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests and write summary
+              run: |
+                # Generate potentially large summary content
+                content=$(cat test-results.md 2>/dev/null || echo "No results")
+
+                # Enforce safe limit: 1 MiB minus 10 KB buffer
+                max_bytes=$(( 1048576 - 10240 ))
+                content_bytes=${#content}
+
+                if [ "$content_bytes" -gt "$max_bytes" ]; then
+                  content="${content:0:$max_bytes}"
+                  content="${content}"$'\n\n> **Note:** Summary truncated — exceeded safe 1 MiB limit.'
+                fi
+
+                printf '%s' "$content" >> "$GITHUB_STEP_SUMMARY"
+  - language: yaml
+    label: 'Truncate step summary to safe size before writing (PowerShell)'
+    code: |
+      jobs:
+        test:
+          runs-on: windows-latest
+          steps:
+            - name: Write test summary with size guard
+              shell: pwsh
+              run: |
+                $content = Get-Content test-results.md -Raw -ErrorAction SilentlyContinue
+                if (-not $content) { $content = "No test results found." }
+
+                # Safe limit: 1 MiB minus 10 KB buffer (accounts for off-by-one bug)
+                $maxBytes = 1048576 - 10240
+                $bytes = [System.Text.Encoding]::UTF8.GetByteCount($content)
+
+                if ($bytes -gt $maxBytes) {
+                  # Truncate and add warning marker
+                  $truncated = $content.Substring(0, [Math]::Min($content.Length, $maxBytes / 2))
+                  $content = $truncated + "`n`n> **Note:** Summary truncated — exceeded safe 1 MiB limit."
+                }
+
+                $content | Out-File -Append -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8
+prevention:
+  - 'Always apply a size guard before writing to GITHUB_STEP_SUMMARY — use (1 MiB - 10 KB) as a safe upper bound'
+  - 'For test result summaries, limit to the N most-recent or most-critical failures rather than dumping all output'
+  - 'Verify critical summary writes by checking file size after the write step, not by relying on exit code 0'
+  - 'Track actions/runner#4337 for a runner fix that either raises the limit or surfaces an error when content is discarded'
+  - 'Split large summaries across multiple steps — but note each step has its own 1 MiB budget, not a shared pool'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4337'
+    label: 'actions/runner#4337: GITHUB_STEP_SUMMARY content silently dropped when size approaches 1 MiB limit (April 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary'
+    label: 'GitHub Docs: Adding a job summary — GITHUB_STEP_SUMMARY documentation and limits'

package/errors/triggers/pull-request-ready-for-review-type-not-listed.yml

@@ -0,0 +1,101 @@
+id: 'triggers-028'
+title: 'Converting a draft PR to ready-for-review does not trigger `pull_request` workflow unless `ready_for_review` is explicitly listed in `types:`'
+category: triggers
+severity: silent-failure
+tags:
+  - pull-request
+  - draft
+  - ready-for-review
+  - types
+  - trigger
+  - silent-failure
+patterns:
+  - regex: 'ready_for_review'
+    flags: 'i'
+  - regex: 'pull_request\.draft\s*==\s*false'
+    flags: 'i'
+error_messages:
+  - 'Workflow not triggered when draft PR converted to ready for review'
+  - 'No workflow runs appeared after marking PR as ready for review'
+root_cause: |
+  GitHub fires a distinct pull_request event type — ready_for_review — when a draft PR
+  is converted to ready. This event type is NOT included in the default types list
+  of [opened, synchronize, reopened].
+
+  Two common misconfigured patterns that silently fail:
+
+  Pattern 1 — draft filter with default types:
+    A workflow uses `if: github.event.pull_request.draft == false` with default types.
+    The if: condition filters jobs correctly on synchronize/opened events, but the
+    ready_for_review conversion event is never fired because ready_for_review is not
+    in the types list. Result: a PR opened as draft, then converted to ready, will
+    never have had CI run against its commits.
+
+  Pattern 2 — only ready_for_review type:
+    A workflow lists only `types: [ready_for_review]`. This fires once when the draft
+    is converted, but never on subsequent commits to the PR (synchronize is not listed).
+
+  The correct pattern combines all four types AND adds the draft check condition so
+  that draft-state pushes are skipped while draft-to-ready conversion and subsequent
+  synchronize events all trigger the workflow.
+
+  Source: Stack Overflow #73948443 (score 8, 4,466 views), GitHub Docs pull_request
+  event types documentation.
+fix: |
+  Combine all required event types including ready_for_review in the types: list, and
+  add a job-level if: condition to skip workflow runs while the PR is still in draft.
+
+  This ensures:
+  - Draft PRs do not run CI (filtered by the if: condition)
+  - Converting a draft to ready fires the workflow against the current HEAD commit
+  - Subsequent commits to a ready PR trigger the workflow via synchronize events
+fix_code:
+  - language: yaml
+    label: 'Correct configuration: all four types plus draft guard condition'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review   # Must be explicit — not included in default types
+
+      jobs:
+        ci:
+          # Skip while PR is in draft state — fires for all non-draft PR events above
+          if: '! github.event.pull_request.draft'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "CI running on non-draft PR"
+  - language: yaml
+    label: 'Alternative: run on all PR events, annotate draft runs as informational'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Annotate draft status
+              if: github.event.pull_request.draft == true
+              run: echo "::notice::Running on draft PR — results are informational"
+
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'Always explicitly list all four pull_request types when your workflow must run on draft-to-ready conversions'
+  - 'Validate your trigger configuration by: opening a draft PR, pushing a commit to it, then converting to ready — all three events should behave as expected'
+  - 'Use github.event.pull_request.draft in job-level if: conditions rather than filtering by type alone, so the same workflow handles draft and non-draft PRs correctly'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'GitHub Docs: pull_request event types including ready_for_review'
+  - url: 'https://stackoverflow.com/questions/73948443/github-actions-running-a-workflow-on-non-draft-prs'
+    label: 'Stack Overflow #73948443: Running a workflow on non-draft PRs (score 8, 4,466 views)'

package/package.json

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