@htekdev/actions-debugger 1.0.108 → 1.0.110

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

@@ -0,0 +1,92 @@
+id: caching-artifacts-064
+title: 'Third-party actions bundling @actions/cache npm v3 return "Cache service responded with 422" after Dec 2024 backend migration'
+category: caching-artifacts
+severity: error
+tags:
+  - actions-cache
+  - deprecated-api
+  - cache-backend
+  - 422
+  - npm-package
+  - third-party-action
+  - migration
+patterns:
+  - regex: 'Cache service responded with 422'
+    flags: 'i'
+  - regex: 'Failed to save cache.*422|Failed to restore cache.*422'
+    flags: 'i'
+  - regex: 'cache.*HTTP 422|HTTP 422.*cache'
+    flags: 'i'
+error_messages:
+  - "Cache service responded with 422"
+  - "Error: Cache service responded with 422"
+  - "Failed to save cache: Cache service responded with 422"
+  - "Warning: Failed to restore cache: Cache service responded with 422"
+root_cause: |
+  In December 2024, GitHub migrated the Actions cache backend to a new service API.
+  The deprecated v3 cache API endpoints now return HTTP 422 instead of processing
+  cache requests. Any action that embeds `@actions/cache` npm package at v3.x sends
+  requests to the old endpoint and receives 422 responses.
+
+  This affects any action — not just `actions/cache` itself — that bundles the old
+  `@actions/cache` npm package internally. Common affected actions:
+  - `actions/setup-node@v2` / `@v3` (embed @actions/cache v3)
+  - `actions/setup-python@v4` and earlier
+  - `actions/setup-go@v4` and earlier
+  - Custom or third-party JavaScript/composite actions that haven't updated
+    their package-lock.json since early 2024
+
+  The 422 error appears in the step output but the visible message does not mention
+  deprecated API versions or npm package issues — it only shows the HTTP status code.
+
+  Note: This is distinct from `caching-artifacts-056` (actions/cache v1/v2 hard
+  deprecation which shows "automatically failed because it uses a deprecated version").
+  That error comes from the version check; this error comes from the actual API call.
+fix: |
+  Upgrade the affected action to a version that bundles `@actions/cache` npm v4+.
+  For first-party GitHub actions, use the latest major version:
+  - `actions/setup-node`   → upgrade to @v4 or @v5
+  - `actions/setup-python` → upgrade to @v5
+  - `actions/setup-go`     → upgrade to @v5
+  - `actions/cache` used directly → upgrade to @v4
+
+  For third-party actions, open an issue asking the maintainer to update
+  @actions/cache in their package-lock.json and re-bundle the action.
+
+  As a temporary workaround, disable caching in the action to unblock CI:
+fix_code:
+  - language: yaml
+    label: 'Upgrade setup-* actions to latest major version with updated cache client'
+    code: |
+      # Before (bundled @actions/cache v3 — returns 422 after Dec 2024 migration)
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      # After (@actions/cache v4+ bundled — compatible with current cache service)
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+  - language: yaml
+    label: 'Disable caching as temporary workaround if action cannot be upgraded'
+    code: |
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          cache: ''   # empty string disables cache, avoids 422 until action is upgraded
+prevention:
+  - 'Keep all setup-* actions at their latest major version to stay compatible with the cache service API'
+  - 'Audit all uses: references for versions older than January 2024 — they may bundle stale @actions/cache v3'
+  - 'Enable Dependabot version updates for GitHub Actions to automatically surface major version bumps'
+  - 'After any GitHub changelog cache-migration notice, scan workflows for outdated action pins'
+docs:
+  - url: 'https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions'
+    label: 'GitHub Changelog — Notice of cache migration and deprecated action versions (Dec 2024)'
+  - url: 'https://github.com/actions/toolkit/tree/main/packages/cache'
+    label: 'actions/toolkit — @actions/cache npm package changelog'
+  - url: 'https://github.com/actions/setup-node/issues/1275'
+    label: 'actions/setup-node#1275 — Cache service 422 errors with older action versions (13 reactions)'
+  - url: 'https://github.com/orgs/community/discussions/155534'
+    label: 'GitHub Community — Cache service 422 flaky restores during Dec 2024 migration'

package/errors/known-unsolved/cross-job-tmp-files-separate-runners.yml

@@ -0,0 +1,121 @@
+id: known-unsolved-057
+title: 'Jobs run on separate fresh runners — /tmp and filesystem are not shared between jobs'
+category: known-unsolved
+severity: limitation
+tags:
+  - jobs
+  - runner
+  - filesystem
+  - tmp
+  - isolation
+  - artifacts
+  - cross-job
+  - runner-environment
+patterns:
+  - regex: 'No such file or directory.*/tmp/'
+    flags: 'i'
+  - regex: 'ENOENT.*no such file.*tmp|cannot.*open.*/tmp/.*no such'
+    flags: 'i'
+  - regex: 'file.*not found.*/tmp|/tmp/.*does not exist'
+    flags: 'i'
+error_messages:
+  - "/tmp/output.json: No such file or directory"
+  - "Error: ENOENT: no such file or directory, open '/tmp/result.txt'"
+  - "/tmp/build-manifest.json: No such file or directory"
+root_cause: |
+  Each job in a GitHub Actions workflow runs on a completely separate, freshly
+  provisioned runner instance. There is NO shared filesystem between jobs. Files
+  written to `/tmp`, `$RUNNER_TEMP`, `$GITHUB_WORKSPACE`, or any other path during
+  one job are invisible to all subsequent jobs.
+
+  This is a fundamental architectural property: GitHub provisions a new virtual machine
+  for each job. The previous job's VM is terminated before the next job starts. No
+  filesystem state survives the job boundary.
+
+  Common patterns that fail for this reason:
+  1. Build job writes `/tmp/report.json` → deploy job tries to read `/tmp/report.json`
+  2. Test job saves coverage to `$RUNNER_TEMP/coverage.xml` → reporter job looks for it
+  3. Compile job produces `./dist/app` → signing job tries to use `./dist/app` without
+     re-downloading it via artifacts
+  4. First job exports env vars via `$GITHUB_ENV` → second job expects those env vars
+     (env vars set via GITHUB_ENV are also job-scoped and do not persist)
+  5. Steps within the SAME job DO share `/tmp` and the workspace — the limitation is
+     specifically at the JOB boundary
+
+  Self-hosted runner pools with persistent workspaces can accidentally appear to share
+  state between jobs on the same machine, but this is unreliable (another job may have
+  cleaned the directory) and creates security risks (secret leakage between runs).
+fix: |
+  There is no mechanism to share filesystem state between jobs without explicitly
+  transferring the data. Two patterns solve this:
+
+  1. Use `actions/upload-artifact` at the end of the producing job and
+     `actions/download-artifact` at the start of the consuming job.
+     Best for: files, binaries, test results, build outputs.
+
+  2. Use job `outputs:` to pass small string values. The producing job emits
+     `echo "key=value" >> $GITHUB_OUTPUT` and declares it under `outputs:`.
+     The consuming job reads it as `needs.<job>.outputs.<key>`.
+     Best for: version strings, commit SHAs, boolean flags, counts.
+fix_code:
+  - language: yaml
+    label: 'Pass files between jobs using upload-artifact / download-artifact'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build binary
+              run: make build   # produces ./dist/app
+
+            - name: Upload for next job
+              uses: actions/upload-artifact@v4
+              with:
+                name: app-binary
+                path: ./dist/app   # upload so sign job can download it
+
+        sign:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download binary
+              uses: actions/download-artifact@v4
+              with:
+                name: app-binary
+                path: ./dist
+
+            - name: Sign binary
+              run: cosign sign ./dist/app
+  - language: yaml
+    label: 'Pass small string data between jobs using job outputs'
+    code: |
+      jobs:
+        compute-version:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.ver.outputs.version }}
+          steps:
+            - id: ver
+              run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: compute-version
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying v${{ needs.compute-version.outputs.version }}"
+prevention:
+  - 'Never rely on /tmp, $RUNNER_TEMP, or workspace paths to share data between jobs — use artifacts or job outputs'
+  - 'Remember: only steps within the same job share a filesystem; different jobs always get separate runners'
+  - 'Use actions/upload-artifact@v4 for files; use job outputs for strings; use caches only for dependency restoration'
+  - 'Environment variables set with GITHUB_ENV are also job-scoped and do not persist across job boundaries'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow'
+    label: 'GitHub Docs — Storing and sharing data between jobs using artifacts'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Docs — Passing information between jobs using outputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/about-github-hosted-runners'
+    label: 'GitHub Docs — About GitHub-hosted runners (each job gets a fresh VM)'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community — Sharing files and filesystem data between workflow jobs'

package/errors/permissions-auth/create-github-app-token-invalid-key-data.yml

@@ -0,0 +1,94 @@
+id: permissions-auth-062
+title: 'create-github-app-token "Invalid keyData" — private key passed via env var with escaped \\n sequences'
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - private-key
+  - invalid-key-data
+  - environment-variable
+  - newlines
+  - create-github-app-token
+  - webcrypto
+patterns:
+  - regex: 'Invalid keyData'
+    flags: 'i'
+  - regex: 'DOMException.*Invalid keyData|DataError.*Invalid keyData'
+    flags: 'i'
+  - regex: 'Failed to create token for .+ \(attempt \d+\): Invalid keyData'
+    flags: 'i'
+error_messages:
+  - "DOMException [DataError]: Invalid keyData"
+  - "Failed to create token for \"repo-name\" (attempt 1): Invalid keyData"
+  - "Failed to create token for \"repo-name\" (attempt 2): Invalid keyData"
+  - "Error: Invalid keyData"
+root_cause: |
+  The `actions/create-github-app-token` action v2+ uses the Web Crypto API
+  (`crypto.subtle.importKey()`) to load the GitHub App private key. This API
+  is strict about key formatting — it throws `DOMException [DataError]: Invalid keyData`
+  if the PEM key material is malformed at the byte level.
+
+  The most common trigger is passing the private key via an environment variable
+  where literal `\n` two-character sequences appear instead of actual newline (0x0A)
+  bytes. This happens when:
+  1. The key is constructed inline in YAML with `"-----BEGIN...\nMIIE...\n-----END..."`
+     where `\n` is a YAML string escape, not a real newline in the multi-line base64 body
+  2. An external CI system or secrets manager serializes the PEM key as a single line
+     with literal backslash-n separators before injecting it into the Actions environment
+  3. Shell variable interpolation collapses the newlines (e.g., `echo $PRIVATE_KEY`)
+
+  The Web Crypto SubtleCrypto API attempts to Base64-decode the key body. When the
+  PEM line breaks are backslash-n characters (0x5C 0x6E) instead of 0x0A, the Base64
+  chunks are malformed and importKey() throws "Invalid keyData" immediately — before
+  any GitHub API call is made.
+
+  This is distinct from "A JSON web token could not be decoded" (permissions-auth-021)
+  which occurs when the key IS imported successfully but the resulting JWT is rejected
+  by GitHub's API — a later-stage failure caused by different formatting issues such
+  as trailing whitespace, CRLF endings, or missing PEM headers.
+fix: |
+  Pass the private key directly as an action input using the GitHub Actions secret
+  expression `${{ secrets.APP_PRIVATE_KEY }}`. When GitHub resolves a secret, it
+  preserves the original stored bytes including actual newlines. Do NOT pass the key
+  through env: variables or inline string construction.
+
+  To store the key with correct newlines, set the secret from the downloaded .pem file
+  using the GitHub CLI:
+    gh secret set APP_PRIVATE_KEY < my-app.private-key.pem
+fix_code:
+  - language: yaml
+    label: 'Correct: pass private key directly as action input from secret'
+    code: |
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}   # newlines preserved by Actions runtime
+  - language: yaml
+    label: 'Wrong: constructing key inline with \\n escape sequences (causes Invalid keyData)'
+    code: |
+      # DO NOT DO THIS — \n are literal two-char sequences, not newlines
+      - name: Broken token generation
+        env:
+          KEY: "-----BEGIN RSA PRIVATE KEY-----\nMIIEow...\n-----END RSA PRIVATE KEY-----"
+        run: |
+          echo "$KEY" > /tmp/key.pem
+          # The action will fail with: DOMException [DataError]: Invalid keyData
+  - language: shell
+    label: 'Set secret from .pem file using GitHub CLI (preserves real newlines)'
+    code: |
+      gh secret set APP_PRIVATE_KEY < my-app.2024-01-15.private-key.pem
+prevention:
+  - 'Always set APP_PRIVATE_KEY secret using `gh secret set KEY < file.pem`, not by pasting the raw PEM text with \\n sequences'
+  - 'Pass the key exclusively as `private-key: ${{ secrets.KEY }}` — never via env: or inline string interpolation'
+  - 'If importing from an external secrets manager, ensure the manager preserves actual newline bytes (0x0A) when injecting into GitHub Actions secrets'
+  - 'Verify the secret was set correctly: run `gh secret list` and confirm the key was recently updated'
+docs:
+  - url: 'https://github.com/actions/create-github-app-token'
+    label: 'actions/create-github-app-token README'
+  - url: 'https://github.com/actions/create-github-app-token/issues/184'
+    label: 'actions/create-github-app-token#184 — Invalid keyData when key passed via environment variable'
+  - url: 'https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey'
+    label: 'MDN — SubtleCrypto.importKey() — DOMException DataError causes'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-private-key-for-a-github-app'
+    label: 'GitHub Docs — Generating a private key for a GitHub App'

package/errors/runner-environment/arc-runner-v2332-container-github-env-permission-denied.yml

@@ -0,0 +1,117 @@
+id: runner-environment-178
+title: 'ARC Runner v2.332.0 Regression — Container Job GITHUB_ENV and Workspace Permission Denied'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - container-job
+  - permissions
+  - GITHUB_ENV
+  - non-root
+  - kubernetes
+  - regression
+  - v2.332
+patterns:
+  - regex: 'cannot create /__w/_temp/_runner_file_commands/set_env_[0-9a-f]+: Permission denied'
+    flags: 'i'
+  - regex: 'cannot create /__w/_temp/_runner_file_commands/add_path_[0-9a-f]+: Permission denied'
+    flags: 'i'
+  - regex: 'fatal: detected dubious ownership in repository at .+/__w/'
+    flags: 'i'
+  - regex: '_runner_file_commands.*Permission denied'
+    flags: 'i'
+error_messages:
+  - "/__w/_temp/36e38446.sh: 5: cannot create /__w/_temp/_runner_file_commands/set_env_7bb88aaa: Permission denied"
+  - "fatal: detected dubious ownership in repository at '/__w/repo/repo'"
+  - "/__w/_temp/_runner_file_commands/add_path_: Permission denied"
+root_cause: |
+  Upgrading Actions Runner Controller (ARC) from runner v2.330.0 to v2.332.0
+  introduces a compound regression that breaks container jobs using non-root users.
+
+  The regression spans two runner releases:
+
+  1. v2.331.0 changed the runner container base image from Ubuntu 22.04 to
+     Ubuntu 24.04. The newer base ships git 2.43+ which enforces stricter
+     safe.directory checks. The mounted workspace volume is owned by the runner
+     UID, so a container running as a different non-root UID receives
+     "fatal: detected dubious ownership" on any git operation.
+
+  2. v2.332.0 bumped container hooks to v0.8.1, which updated workspace
+     ownership handling for the runner pod itself — but not for downstream job
+     containers. The _runner_file_commands directory under /__w/_temp/ is
+     still created with runner UID ownership. When a container step writes to
+     $GITHUB_ENV, $GITHUB_OUTPUT, $GITHUB_PATH, or $GITHUB_STEP_SUMMARY via a
+     shell redirect, the shell (running as the container's non-root user) cannot
+     create the file and exits non-zero.
+
+  This regression affects:
+  - ARC-managed self-hosted runners on Kubernetes (EKS, GKE, AKS, on-prem)
+  - Any workflow using `container: image: my-image` with `options: --user <uid>`
+    or a non-root USER in the Dockerfile
+  - Workflows that previously worked on runner v2.330.0 and below
+
+  GitHub-hosted runners (ubuntu-latest, etc.) are NOT affected.
+fix: |
+  If you cannot immediately pin the runner version, add a workaround step at
+  the top of the affected job to fix ownership of the runner file command
+  directories. Alternatively, pin ARC runner images to v2.330.0 until an
+  upstream fix for container hooks is released.
+
+  The most robust long-term fix is to explicitly add the workspace to git's
+  safe.directory list and pre-create the file command directories with the
+  correct ownership.
+fix_code:
+  - language: yaml
+    label: 'Option A — Pre-create _runner_file_commands with container user ownership'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          container:
+            image: my-app:latest
+            options: --user 1000
+          steps:
+            - name: Fix runner file command directory ownership (v2.332.0 workaround)
+              # Run as root before any steps that use GITHUB_ENV/GITHUB_OUTPUT
+              run: |
+                chown -R 1000:1000 /__w/_temp/_runner_file_commands/ || true
+                git config --global --add safe.directory /__w/${{ github.repository }}
+              shell: bash
+              # Note: requires container image to have chown available as root
+  - language: yaml
+    label: 'Option B — Pin ARC runner image to v2.330.0 to avoid the regression'
+    code: |
+      # In your ARC HelmRelease or RunnerDeployment spec:
+      # spec:
+      #   template:
+      #     spec:
+      #       containers:
+      #         - name: runner
+      #           image: ghcr.io/actions/actions-runner:2.330.0
+  - language: yaml
+    label: 'Option C — Run container job as root to avoid UID mismatch'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          container:
+            image: my-app:latest
+            options: --user root   # avoid UID mismatch until ARC fix ships
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "FOO=bar" >> $GITHUB_ENV
+prevention:
+  - 'Test ARC runner version upgrades in a staging environment before rolling out to production — especially major bumps (v2.330 → v2.332).'
+  - 'Pin container jobs to run as root if your workflow uses GITHUB_ENV, GITHUB_OUTPUT, or GITHUB_PATH writes and you depend on non-root containers.'
+  - 'Subscribe to actions/runner releases and scan for changes to container-hooks between minor versions.'
+  - 'Add a smoke-test workflow that writes to GITHUB_ENV in a non-root container job — run it against each ARC upgrade to catch regressions early.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4302'
+    label: 'actions/runner #4302 — v2.332.0: Container jobs fail with permission denied on GITHUB_ENV and workspace'
+  - url: 'https://github.com/actions/runner/issues/4131'
+    label: 'actions/runner #4131 — Permissions issue on runners v2.330.0 (/home/runner ownership regression)'
+  - url: 'https://github.com/actions/runner/issues/4251'
+    label: 'actions/runner #4251 — TempDirectoryManager fails to clean temp directory (permission denied on v2.331.0)'
+  - url: 'https://github.com/actions/runner-container-hooks/issues/282'
+    label: 'runner-container-hooks #282 — Permissions denied on workingDir'

package/errors/runner-environment/node24-16-toolcache-regression-browser-install-fails.yml

@@ -0,0 +1,109 @@
+id: runner-environment-177
+title: 'Node.js 24.16.0 Toolcache Update Breaks Puppeteer, Playwright, and Cypress Browser Install'
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node24
+  - puppeteer
+  - playwright
+  - cypress
+  - toolcache
+  - browser-install
+  - extract-zip
+  - regression
+patterns:
+  - regex: 'Could not find Chrome \(ver\. \d+\.\d+\.\d+'
+    flags: 'i'
+  - regex: 'npx puppeteer browsers install .+ exited with code [^0]'
+    flags: 'i'
+  - regex: 'browserType\.launch: Executable doesn.t exist at .+/chromium'
+    flags: 'i'
+  - regex: 'Cannot find browser at path.*\.cache/puppeteer'
+    flags: 'i'
+  - regex: 'Failed to install browsers.*extract.*zip'
+    flags: 'i'
+error_messages:
+  - "Error: Could not find Chrome (ver. 146.0.7680.153). This can occur if either 1. you did not perform an installation before running the script (e.g. `npx puppeteer browsers install chrome-headless-shell`) or 2. your cache path is incorrectly configured"
+  - "browserType.launch: Executable doesn't exist at /home/runner/.cache/ms-playwright/chromium-1169/chrome-linux/chrome"
+  - "Error: Failed to install browsers at /home/runner/.cache/ms-playwright"
+root_cause: |
+  The ubuntu-24.04 image update from 20260518.149.1 → 20260525.161.1 bumped the
+  cached Node.js toolcache version from 24.15.0 to 24.16.0. Node.js 24.16.0
+  contains an upstream regression in the readable-stream.destroy() lifecycle
+  that breaks yauzl (a ZIP reading library) and extract-zip which depends on it.
+
+  The affected tools all use @puppeteer/browsers or equivalent ZIP-based browser
+  downloaders internally:
+  - Puppeteer: `npx puppeteer browsers install chrome-headless-shell`
+  - Playwright: `npx playwright install chromium` / `npx playwright install --with-deps`
+  - Cypress: `npx cypress install`
+
+  The ZIP archive download completes successfully and the partial extraction
+  begins, but the stream destroy bug causes yauzl to exit before all entries
+  are written. The browser binary never lands on disk. The browser installer
+  exits 0 (or a non-descriptive exit code) and the next step fails with
+  "Could not find Chrome at path..." or a missing executable error.
+
+  Root upstream issues:
+  - https://github.com/nodejs/node/issues/63487 (yauzl/extract-zip hang / partial extraction)
+  - https://github.com/nodejs/node/issues/63638 (libuv regression on Windows)
+
+  Because actions/setup-node resolves to the cached Node.js 24.16.0 when
+  node-version: '24' or node-version: '24.x' is specified (or when using the
+  default runner-baked Node 24 on ubuntu-24.04), every workflow that installs
+  a browser via these tools is affected until Node.js 24.17.0 ships a fix.
+fix: |
+  Pin Node.js to 24.15.0 (the last known-good version) via actions/setup-node
+  until Node.js 24.17.0 is published and rolled into the runner toolcache.
+
+  If your workflow does not strictly require Node.js 24, fall back to Node.js 22
+  (the runner image default), which is unaffected by this regression.
+
+  Do NOT use node-version: '24' or node-version: 'latest' until the upstream
+  fix lands in Node.js 24.17.0.
+fix_code:
+  - language: yaml
+    label: 'Option A — Pin Node.js to 24.15.0 (last known-good release)'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '24.15.0'   # pin until Node 24.17.0 fixes readable-stream regression
+            cache: 'npm'
+
+        - name: Install Puppeteer Chrome
+          run: npx puppeteer browsers install chrome-headless-shell
+  - language: yaml
+    label: 'Option B — Fall back to Node.js 22 (unaffected)'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '22'        # LTS, not affected by readable-stream regression
+            cache: 'npm'
+
+        - name: Install Playwright browsers
+          run: npx playwright install --with-deps chromium
+  - language: yaml
+    label: 'Option C — Pin Playwright install to avoid extract-zip entirely (Playwright only)'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '24.15.0'
+        - uses: microsoft/playwright-github-action@v1   # uses pre-installed image browsers
+prevention:
+  - 'Pin node-version to a specific patch (e.g. 24.15.0) rather than a major/minor range in workflows that install browser binaries via npx commands.'
+  - 'After bumping Node.js versions, verify browser install steps succeed by checking the binary path explicitly with `ls -la ~/.cache/puppeteer` or equivalent before running tests.'
+  - 'Subscribe to actions/runner-images releases to catch toolcache updates that may include Node.js patch regressions.'
+  - 'For Playwright, prefer `npx playwright install --with-deps` combined with an explicit Node.js pin rather than relying on runner-image cached Node versions.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14173'
+    label: 'runner-images #14173 — Puppeteer broken in Ubuntu 24.04 version 20260525.161.1'
+  - url: 'https://github.com/nodejs/node/issues/63487'
+    label: 'nodejs/node #63487 — yauzl/extract-zip hang and partial extraction (readable-stream regression)'
+  - url: 'https://github.com/nodejs/node/issues/63638'
+    label: 'nodejs/node #63638 — libuv regression in Node.js 24.16.0'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'runner-images ubuntu24/20260525.161 release — Node.js toolcache bumped 24.15.0 → 24.16.0'

package/errors/silent-failures/setup-node-falls-through-wrong-version-on-download-failure.yml

@@ -0,0 +1,112 @@
+id: silent-failures-097
+title: 'setup-node Silently Uses Runner-Baked Node Version When Download Fails — Wrong Version Active'
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - nodejs
+  - download-failure
+  - silent-failure
+  - wrong-version
+  - toolcache
+  - hosted-runner
+  - fallthrough
+patterns:
+  - regex: 'Attempting to download \d+\.\d+\.\d+\.\.\.'
+    flags: 'i'
+  - regex: 'Cannot find module.*engines.*node.*>=\s*24'
+    flags: 'i'
+  - regex: 'The engine .node. is incompatible with this module\. Expected version .+\. Got .2[0-2]\.'
+    flags: 'i'
+  - regex: 'ELIFECYCLE.*node --version.*v2[0-2]\.'
+    flags: 'i'
+error_messages:
+  - "Attempting to download 24.15.0..."
+  - "error: The engine 'node' is incompatible with this module. Expected version '>=24.0.0'. Got '22.14.0'"
+  - "npm ERR! code ELIFECYCLE"
+  - "Error: Cannot find module 'node:crypto' (Node.js version too old)"
+root_cause: |
+  When actions/setup-node's download or extract path fails transiently —
+  network blip, manifest miss, partial extract from a concurrent toolcache
+  write, or a transient S3/CDN cache failure — the action does not surface the
+  error. Instead, it falls back to a secondary download path. If that secondary
+  path also fails or returns an unusable toolPath, setup-node adds an empty or
+  incorrect directory to PATH and exits 0 (success).
+
+  Because the setup-node step succeeds, the runner-baked Node.js version
+  (e.g. v22.x on ubuntu-latest after the Node 20 removal) remains on PATH.
+  Downstream steps execute against the wrong Node.js major version with no
+  indication that setup-node did not install the requested version.
+
+  The mechanism (in official_builds.ts, as of 2026-05-21):
+  - Download/extract errors are logged via core.info(), not core.warning()
+    or core.error(), so they are buried in normal output
+  - After the fallback download attempt, there is no post-condition check
+    that verifies node --version matches the requested version
+  - core.addPath() is called even if toolPath/bin is empty or stale
+
+  Reported failing run: https://github.com/n8n-io/n8n/actions/runs/26100630929
+  The run showed "Attempting to download 24.15.0..." → 33 seconds of silence →
+  next step ran against runner-baked v20.20.0 with no error from setup-node.
+
+  This is distinct from silent-failures-028 which covers self-hosted runners
+  where node is completely absent (node: not found). This entry covers hosted
+  runners where the wrong version is silently active and node IS found.
+
+  Root upstream issue: actions/toolkit#804 — concurrent toolcache writes create
+  partial extracts that pass path existence checks.
+fix: |
+  Add an explicit node --version verification step immediately after setup-node
+  and fail the job if the version does not match. This is the external workaround
+  used by affected projects (e.g., n8n/n8n PR #30849).
+
+  Until actions/setup-node ships a built-in post-install assertion, this
+  workflow-level guard is the only reliable way to catch the silent fallthrough.
+fix_code:
+  - language: yaml
+    label: 'Add explicit version verification after setup-node'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '24'
+            cache: 'npm'
+
+        - name: Verify Node.js version
+          shell: bash
+          run: |
+            ACTUAL=$(node --version)
+            EXPECTED_MAJOR="24"
+            if [[ "$ACTUAL" != v${EXPECTED_MAJOR}.* ]]; then
+              echo "::error::setup-node installed Node ${EXPECTED_MAJOR} but \`node --version\` reports $ACTUAL"
+              echo "::error::This usually indicates a transient download failure or partial toolcache extract."
+              exit 1
+            fi
+            echo "Node.js version confirmed: $ACTUAL"
+
+        - name: Install dependencies
+          run: npm ci
+  - language: yaml
+    label: 'Pin to exact patch version to reduce toolcache misses'
+    code: |
+      steps:
+        - uses: actions/setup-node@v6
+          with:
+            node-version: '24.15.0'   # exact pin reduces manifest/toolcache lookup failures
+            cache: 'npm'
+
+        - name: Verify Node.js version (belt-and-suspenders)
+          run: |
+            node --version | grep -E '^v24\.15\.' || (echo "Wrong Node version" && exit 1)
+prevention:
+  - 'Always verify node --version matches the requested major after setup-node, especially in workflows that depend on Node.js 24+ features or native modules.'
+  - 'Pin to an exact patch version (e.g. 24.15.0) rather than a range (24.x) to avoid unexpected toolcache miss fallbacks.'
+  - 'If you see "Attempting to download X.Y.Z..." followed by an unusually long pause in setup-node output, the download may have stalled and the fallback path may be active.'
+  - 'Watch setup-node releases for a built-in post-install assertion fix (tracked in actions/setup-node#1556 and actions/toolkit#804).'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1556'
+    label: 'setup-node #1556 — setup-node silently falls through to runner-baked Node on download/extract failure'
+  - url: 'https://github.com/actions/toolkit/issues/804'
+    label: 'actions/toolkit #804 — Concurrent toolcache writes cause partial extracts on multi-tenant runners'
+  - url: 'https://github.com/n8n-io/n8n/pull/30849'
+    label: 'n8n/n8n PR #30849 — External Verify Node.js Version workaround'

package/errors/yaml-syntax/workflow-dispatch-input-type-object-invalid.yml

@@ -0,0 +1,84 @@
+id: yaml-syntax-067
+title: 'workflow_dispatch input type: object is not valid — "Unexpected value" validation error'
+category: yaml-syntax
+severity: error
+tags:
+  - workflow_dispatch
+  - inputs
+  - type-object
+  - validation-error
+  - yaml
+patterns:
+  - regex: 'on\.workflow_dispatch\.inputs\.\w+\.type.*Unexpected value'
+    flags: 'i'
+  - regex: "Unexpected value 'object'"
+    flags: 'i'
+  - regex: 'Input type .object. is not supported'
+    flags: 'i'
+error_messages:
+  - "Invalid workflow file: on.workflow_dispatch.inputs.config.type: Unexpected value 'object'"
+  - "Invalid workflow file: .github/workflows/deploy.yml: Unexpected value 'object'"
+root_cause: |
+  `workflow_dispatch` inputs support only five types: `string`, `boolean`, `choice`,
+  `environment`, and `number`. There is no `object` type. Developers attempting to pass
+  complex structured data (JSON objects, arrays) via a workflow_dispatch input often
+  try `type: object`, which causes an immediate YAML schema validation error and
+  prevents the workflow from running at all.
+
+  The valid type list:
+  - string      — plain text value
+  - boolean     — true/false checkbox in UI
+  - choice      — dropdown from a fixed options list
+  - environment — GitHub environment picker
+  - number      — numeric value (coerced to string at runtime)
+
+  There is no object, array, list, or json type for workflow_dispatch inputs.
+  The workflow file fails validation and does not appear as runnable in the
+  Actions UI.
+fix: |
+  Use `type: string` and serialize the complex data as a JSON string. Parse it inside
+  the workflow using the `fromJSON()` expression function or `jq` in a run step.
+fix_code:
+  - language: yaml
+    label: 'Pass complex data as a JSON string — use type: string, not type: object'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            config:
+              type: string          # NOT type: object
+              description: 'JSON config e.g. {"env":"prod","replicas":3}'
+              default: '{}'
+              required: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Parse config input
+              run: |
+                ENV=$(echo '${{ inputs.config }}' | jq -r .env)
+                REPLICAS=$(echo '${{ inputs.config }}' | jq -r .replicas)
+                echo "Deploying to $ENV with $REPLICAS replicas"
+  - language: yaml
+    label: 'Access nested fields with fromJSON() in expressions'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            ENV_NAME: ${{ fromJSON(inputs.config).env }}
+          steps:
+            - run: echo "Environment is $ENV_NAME"
+prevention:
+  - 'Only use type: string, boolean, choice, environment, or number for workflow_dispatch inputs'
+  - 'For structured data, serialize as a JSON string and parse inside the job with jq or fromJSON()'
+  - 'Use actionlint to catch unsupported input types before pushing the workflow file'
+  - 'Document the expected JSON schema in the input description field so callers know the format'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs — workflow_dispatch inputs (valid types: string, boolean, choice, environment, number)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'GitHub Docs — fromJSON() expression function'
+  - url: 'https://stackoverflow.com/questions/76181396/github-actions-workflow-with-input-type-object-not-running'
+    label: 'Stack Overflow — workflow_dispatch with input type object not running'

package/package.json

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