@htekdev/actions-debugger 1.0.93 → 1.0.95

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

@@ -0,0 +1,107 @@
+id: caching-artifacts-052
+title: '`download-artifact@v4` `name:` Does Not Support Glob Patterns — Use `pattern:` Instead'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v4-breaking-change
+  - glob
+  - pattern
+  - migration
+  - artifact-download
+patterns:
+  - regex: 'download-artifact@v4|download-artifact@v3.*name.*\*'
+    flags: 'i'
+  - regex: 'name\s*:\s*[''"][^''"]*\*[^''"]*[''"]'
+    flags: 'i'
+error_messages:
+  - "No artifacts found with the provided name"
+  - "Error: Unable to find any artifacts for the associated workflow"
+  - "Unable to find artifact 'my-*-artifact'"
+root_cause: |
+  In `actions/download-artifact@v3`, the `name:` input accepted glob patterns
+  (e.g., `name: 'build-*'`) and would download all matching artifacts.
+  In `actions/download-artifact@v4` this behavior changed: `name:` now requires
+  an EXACT artifact name match. Glob characters in `name:` are treated as
+  literal characters, so `name: 'build-*'` looks for an artifact literally
+  named `build-*`, finds none, and either errors or silently downloads nothing
+  depending on the `error-no-files-found` setting.
+
+  The `pattern:` input was introduced in v4 as the replacement for glob-based
+  artifact selection. Migrating from v3 to v4 requires moving glob expressions
+  from `name:` to `pattern:`.
+
+  This silently impacts workflows that:
+  - Download multiple build artifacts from matrix jobs using a shared prefix
+  - Use wildcards to grab all artifacts from a set of parallel jobs
+  - Were migrated to v4 without reading the full migration guide
+fix: |
+  Replace glob patterns in `name:` with the `pattern:` input in
+  `actions/download-artifact@v4`. The `name:` input should only be used
+  when downloading a single artifact by its exact name.
+
+  When using `pattern:`, the action also has a `merge-multiple` option
+  that controls whether matched artifacts are merged into one directory
+  or placed in separate subdirectories.
+fix_code:
+  - language: yaml
+    label: "WRONG — glob in name: silently matches nothing in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            name: 'build-*'      # ❌ globs not supported in name: for v4
+            path: ./artifacts
+  - language: yaml
+    label: "RIGHT — use pattern: for glob matching in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            pattern: 'build-*'   # ✅ use pattern: for glob matching
+            path: ./artifacts
+            merge-multiple: true # flatten into single directory
+  - language: yaml
+    label: "RIGHT — download exact artifact by name in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            name: build-linux-amd64   # ✅ exact name, no glob needed
+            path: ./dist/linux
+  - language: yaml
+    label: "Matrix upload + glob download pattern"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [linux, windows, macos]
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ matrix.os }}   # distinct name per job
+                path: ./dist/
+
+        package:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: 'build-*'      # ✅ downloads all build-* artifacts
+                path: ./all-builds
+                merge-multiple: false   # keep per-artifact subdirectories
+prevention:
+  - "When migrating from download-artifact@v3 to @v4, audit all `name:` inputs for glob characters and move them to `pattern:`."
+  - "Use `name:` only for exact single-artifact downloads; use `pattern:` for any glob or multi-artifact download."
+  - "Set `error-no-files-found: error` to fail fast when no artifacts match, exposing glob issues early."
+  - "Review the download-artifact v4 migration guide before updating the action version."
+docs:
+  - url: "https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md"
+    label: "download-artifact v4 migration guide"
+  - url: "https://github.com/actions/download-artifact#inputs"
+    label: "download-artifact — inputs reference (pattern vs name)"
+  - url: "https://github.com/actions/toolkit/releases/tag/%40actions%2Fartifact%402.0.0"
+    label: "actions/toolkit v2 — artifact v2 API underlying v4 action"

package/errors/known-unsolved/known-unsolved-053.yml

@@ -0,0 +1,114 @@
+id: known-unsolved-053
+title: '`workflow_dispatch` Has No Native Array or List Input Type — Must Serialize as JSON String'
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow_dispatch
+  - inputs
+  - array
+  - list
+  - json
+  - limitation
+patterns:
+  - regex: 'workflow_dispatch.*inputs|inputs.*type\s*:\s*string.*array'
+    flags: 'im'
+  - regex: "fromJSON\\(.*inputs\\."
+    flags: 'i'
+error_messages:
+  - "Input type 'array' is not supported for workflow_dispatch"
+  - "Unexpected value 'array'"
+root_cause: |
+  GitHub Actions `workflow_dispatch` supports only five input types:
+  `string`, `boolean`, `choice`, `number`, and `environment`. There is no
+  native `array` or `list` type. Users who need to pass multiple values
+  (e.g., a list of services to deploy, a set of environments to target)
+  must serialize the array as a JSON string and parse it in the workflow.
+
+  This limitation affects:
+  - Manual dispatch with dynamic target lists
+  - CI/CD automation via the REST API (`POST /repos/.../actions/workflows/.../dispatches`)
+  - Reuse of workflow_dispatch workflows that naturally accept variable-length input
+  - Validation — no schema can prevent malformed JSON from being passed
+
+  A `type: array` schema was proposed in actions/runner#1844 (800+ reactions)
+  and remains one of the highest-voted open feature requests for GitHub Actions.
+fix: |
+  Serialize the array as a JSON string in the dispatch call and use
+  `fromJSON()` in the workflow to parse it into a matrix or loop variable.
+
+  Workarounds by use case:
+  1. **API dispatch**: Serialize to `'["a","b","c"]'` and use `fromJSON(inputs.targets)`
+  2. **UI dispatch**: Document the expected JSON format in the input description
+  3. **Choice type**: If the list is finite and known ahead of time, use
+     `type: choice` with predefined options instead
+  4. **Multiple boolean inputs**: For small fixed sets, use separate boolean
+     inputs per option (verbose but typed)
+fix_code:
+  - language: yaml
+    label: "Workaround — serialize array as JSON string, parse with fromJSON"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            services:
+              description: 'JSON array of services to deploy e.g. ["api","worker","ui"]'
+              required: true
+              type: string
+              default: '["api","worker"]'
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              service: ${{ fromJSON(inputs.services) }}
+          steps:
+            - run: echo "Deploying ${{ matrix.service }}"
+  - language: yaml
+    label: "Workaround — comma-separated string split in shell"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environments:
+              description: 'Comma-separated environments e.g. staging,production'
+              required: true
+              type: string
+              default: 'staging'
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to each environment
+              run: |
+                IFS=',' read -ra ENVS <<< "${{ inputs.environments }}"
+                for env in "${ENVS[@]}"; do
+                  echo "Deploying to: $env"
+                done
+  - language: yaml
+    label: "Alternative — use type: choice for known finite sets"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            target_env:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options:
+                - staging
+                - production
+                - both
+prevention:
+  - "Document the expected JSON format in the input `description` field so UI dispatchers know the required syntax."
+  - "Add a validation step that runs `echo '${{ inputs.targets }}' | jq .` to fail fast on malformed JSON before processing."
+  - "Consider using `type: choice` with predefined options if the list is small and known at workflow-definition time."
+  - "For API-driven workflows, generate the JSON array programmatically and pass it as a string in the dispatch payload."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputsinput_idtype"
+    label: "workflow_dispatch input types — supported values"
+  - url: "https://github.com/actions/runner/issues/1844"
+    label: "actions/runner #1844 — Support array inputs for workflow_dispatch (800+ reactions)"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API — Create a workflow dispatch event"

package/errors/permissions-auth/permissions-auth-053.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-053
+title: 'GITHUB_TOKEN `packages: write` Cannot Delete Package Versions — Requires PAT with `delete:packages`'
+category: permissions-auth
+severity: error
+tags:
+  - packages
+  - github-token
+  - delete-packages
+  - container-registry
+  - package-cleanup
+  - permissions
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'DELETE.*packages.*versions|packages.*DELETE.*versions'
+    flags: 'i'
+  - regex: '403.*package|package.*403'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "403 Forbidden — DELETE https://api.github.com/user/packages/{type}/{name}/versions/{id}"
+  - "Error: Resource not accessible by integration (HTTP 403)"
+root_cause: |
+  The `packages: write` permission in `GITHUB_TOKEN` grants the ability to
+  publish and overwrite package versions but does NOT include the ability to
+  delete them. Package version deletion requires account-level permission
+  (`delete:packages` OAuth scope) that cannot be granted to an installation
+  token. The GitHub Packages REST API delete endpoint
+  (`DELETE /user/packages/{type}/{name}/versions/{id}` or the org equivalent)
+  validates the caller's account-level scope, which GITHUB_TOKEN—being a
+  repository-scoped installation token—can never satisfy regardless of the
+  `permissions: packages: write` declaration in the workflow.
+
+  This commonly surfaces in:
+  - Container image cleanup jobs that try to prune old tags/digests
+  - npm, Maven, or RubyGems package version retention workflows
+  - Automated housekeeping that uses `ghcr.io` image management actions
+fix: |
+  Store a fine-grained or classic PAT with `delete:packages` scope as a
+  repository secret (e.g., `PACKAGES_DELETE_TOKEN`) and use that token when
+  calling the Packages delete API or actions that delete package versions.
+
+  For GitHub Container Registry (ghcr.io) image pruning, use a PAT or a
+  GitHub App installation token with Packages write + admin scope. Pass it
+  as the `token:` input to the relevant cleanup action.
+fix_code:
+  - language: yaml
+    label: "WRONG — GITHUB_TOKEN cannot delete package versions (403)"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          permissions:
+            packages: write   # ❌ write permission does not grant delete
+          steps:
+            - name: Delete old package version
+              run: |
+                # This call will return 403 "Resource not accessible by integration"
+                VERSION_ID=12345
+                curl -X DELETE \
+                  -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+                  https://api.github.com/user/packages/container/my-image/versions/$VERSION_ID
+  - language: yaml
+    label: "RIGHT — use a PAT with delete:packages scope"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Delete old package version
+              env:
+                GH_TOKEN: ${{ secrets.PACKAGES_DELETE_TOKEN }}  # PAT with delete:packages
+              run: |
+                VERSION_ID=12345
+                curl -X DELETE \
+                  -H "Authorization: Bearer $GH_TOKEN" \
+                  https://api.github.com/user/packages/container/my-image/versions/$VERSION_ID
+  - language: yaml
+    label: "RIGHT — ghcr.io cleanup action with PAT"
+    code: |
+      jobs:
+        cleanup-images:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: snok/container-retention-policy@v3
+              with:
+                account: user
+                token: ${{ secrets.PACKAGES_DELETE_TOKEN }}  # PAT with delete:packages
+                image-names: my-image
+                cut-off: 7 days ago UTC
+                keep-n-most-recent: 5
+prevention:
+  - "Never assume `packages: write` is sufficient for full package lifecycle management — deletion is always PAT-only."
+  - "Create a dedicated PAT or GitHub App with `delete:packages` scope and store it as a secret for cleanup workflows."
+  - "Scope cleanup jobs separately from build jobs so the PAT is only used where deletion is needed."
+  - "Document in your workflow that PACKAGES_DELETE_TOKEN requires `delete:packages` scope so it is renewed with the right scopes."
+docs:
+  - url: "https://docs.github.com/en/rest/packages/packages#delete-a-package-version-for-a-user"
+    label: "REST API — Delete a package version for a user"
+  - url: "https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries"
+    label: "About permissions for GitHub Packages"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "Creating a fine-grained PAT with delete:packages"

package/errors/runner-environment/macos-xcrun-simctl-no-developer-tools.yml

@@ -0,0 +1,84 @@
+id: runner-environment-161
+title: 'macOS ARM64 runners: xcrun simctl fails — Xcode developer tools not selected'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcrun
+  - simctl
+  - xcode
+  - ios
+  - arm64
+  - xcode-select
+  - macos-14
+  - macos-15
+patterns:
+  - regex: 'xcrun: error: unable to find utility "simctl"'
+    flags: 'i'
+  - regex: 'xcode-select.*tool.*requires Xcode'
+    flags: 'i'
+  - regex: 'active developer directory.*command line tools instance'
+    flags: 'i'
+  - regex: 'xcode-select: note: No developer tools were found'
+    flags: 'i'
+error_messages:
+  - 'xcrun: error: unable to find utility "simctl", not a developer tool or in PATH'
+  - 'xcode-select: error: tool ''xcodebuild'' requires Xcode, but active developer directory ''/Library/Developer/CommandLineTools'' is a command line tools instance'
+  - 'xcode-select: note: No developer tools were found, requesting install'
+root_cause: |
+  macOS 14 (macos-14) and macOS 15 (macos-15) GitHub-hosted runners include
+  multiple Xcode versions and also have Xcode Command Line Tools installed. When
+  the active developer directory is set to the Command Line Tools path
+  (/Library/Developer/CommandLineTools) rather than a full Xcode.app installation,
+  tools that require full Xcode — xcrun simctl, xcodebuild, instruments, codesign,
+  and others — fail with "unable to find utility" or "requires Xcode" errors.
+
+  The runners have a default Xcode selected at image creation time, but this can
+  be changed or reset by steps earlier in the workflow (e.g., a Homebrew install
+  that runs xcode-select internally). iOS simulator builds on the ARM64 macos-14
+  and macos-15 runners are the most common trigger because simctl is exclusively
+  a full Xcode tool with no Command Line Tools counterpart.
+fix: |
+  Explicitly select a full Xcode version using xcode-select or DEVELOPER_DIR at
+  the start of the workflow. List available Xcode versions with
+  ls /Applications/Xcode*.app to find what is pre-installed on the runner.
+fix_code:
+  - language: yaml
+    label: 'Explicitly select Xcode at workflow start'
+    code: |
+      - name: Select Xcode version
+        run: |
+          sudo xcode-select -s /Applications/Xcode_16.2.app
+          xcode-select --print-path
+  - language: yaml
+    label: 'Use DEVELOPER_DIR env var for all Xcode steps'
+    code: |
+      jobs:
+        ios-build:
+          runs-on: macos-15
+          env:
+            DEVELOPER_DIR: /Applications/Xcode_16.2.app/Contents/Developer
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: |
+                xcrun simctl list devicetypes | head -5
+                xcodebuild -scheme MyApp -sdk iphonesimulator build
+  - language: yaml
+    label: 'List available Xcode versions on the runner'
+    code: |
+      - name: List Xcode versions
+        run: ls /Applications/Xcode*.app
+        # Shows all pre-installed Xcode versions to pick the correct path
+prevention:
+  - 'Always run xcode-select -p at the start of iOS/macOS workflows to verify the active developer directory'
+  - 'Pin the Xcode version explicitly using xcode-select or DEVELOPER_DIR instead of relying on runner defaults'
+  - 'Check the runner image README at github.com/actions/runner-images for pre-installed Xcode versions per image'
+  - 'Use the setup-xcode community action for simplified Xcode version selection'
+docs:
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md'
+    label: 'macOS 15 runner image README — pre-installed Xcode versions'
+  - url: 'https://developer.apple.com/documentation/xcode/selecting-the-xcode-that-tools-will-use'
+    label: 'Apple Developer: Selecting the Xcode that tools will use'
+  - url: 'https://github.com/actions/runner-images/issues'
+    label: 'actions/runner-images GitHub Issues — macOS Xcode selection reports'

package/errors/runner-environment/node-22-openssl-legacy-provider-removed.yml

@@ -0,0 +1,96 @@
+id: runner-environment-162
+title: 'Node.js 22 removed --openssl-legacy-provider — webpack 4 and Create React App builds fail'
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node-22
+  - openssl
+  - webpack
+  - create-react-app
+  - lts
+  - setup-node
+  - openssl-legacy-provider
+patterns:
+  - regex: 'ERR_OSSL_UNSUPPORTED'
+    flags: 'i'
+  - regex: '--openssl-legacy-provider is not allowed in NODE_OPTIONS'
+    flags: 'i'
+  - regex: 'error:0308010C:digital envelope routines::unsupported'
+    flags: 'i'
+  - regex: 'opensslErrorStack.*digital envelope routines.*initialization error'
+    flags: 'i'
+error_messages:
+  - 'Error: error:0308010C:digital envelope routines::unsupported'
+  - 'node: --openssl-legacy-provider is not allowed in NODE_OPTIONS'
+  - 'opensslErrorStack: [ ''error:03000086:digital envelope routines::initialization error'' ]'
+root_cause: |
+  Node.js 22 (LTS since October 2024) completed the removal of the
+  --openssl-legacy-provider CLI flag that was first deprecated in Node.js 18.
+  When node-version: 'lts/*' or node-version: '22' in setup-node resolves to
+  Node.js 22, workflows that build webpack 4 projects, older Create React App
+  setups, or any tool using MD4/RC4/legacy OpenSSL algorithms fail with
+  ERR_OSSL_UNSUPPORTED.
+
+  The common Node.js 17/18 workaround of setting
+  NODE_OPTIONS=--openssl-legacy-provider now causes a secondary error:
+  "--openssl-legacy-provider is not allowed in NODE_OPTIONS" on Node.js 22.
+  This double-failure — the original OpenSSL error AND the workaround error —
+  makes the root cause difficult to diagnose.
+
+  This is distinct from runner-environment-111 (setup-node major version upgrade
+  breaking engines field). That entry covers package.json engines compatibility;
+  this entry covers a specific CLI flag removal at the Node.js runtime level.
+fix: |
+  The correct fix is to upgrade webpack to version 5 or migrate the project away
+  from Create React App. As a temporary workaround, pin node-version to '20'
+  while the webpack upgrade is in progress. Do not use --openssl-legacy-provider
+  as it is removed in Node.js 22 and will also error on Node.js 22.
+fix_code:
+  - language: yaml
+    label: 'Pin to Node.js 20 LTS as temporary workaround'
+    code: |
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'   # Pin to Node 20 while upgrading webpack to v5
+          cache: 'npm'
+  - language: yaml
+    label: 'Use .nvmrc to enforce Node version across all environments'
+    code: |
+      # .nvmrc contains: 20
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: 'Test builds against Node.js 22 in a separate matrix job'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              node: ['20', '22']
+            fail-fast: false
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+                cache: 'npm'
+            - run: npm ci
+            - run: npm run build
+prevention:
+  - 'Upgrade to webpack 5 — webpack 4 uses MD4 hashes that depend on legacy OpenSSL algorithms'
+  - 'Do not set NODE_OPTIONS=--openssl-legacy-provider in workflow env — it was a temporary workaround removed in Node 22'
+  - 'Use node-version-file (.nvmrc or .node-version) to prevent automatic major version upgrades when lts/* resolves to a new major'
+  - 'Run a separate CI matrix job targeting Node.js 22 to detect future incompatibilities before they block your default branch'
+docs:
+  - url: 'https://nodejs.org/en/blog/release/v22.0.0'
+    label: 'Node.js 22 release notes — OpenSSL legacy provider removal'
+  - url: 'https://github.com/webpack/webpack/issues/14532'
+    label: 'webpack GitHub issue: ERR_OSSL_UNSUPPORTED on Node.js 17+'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs#specifying-the-nodejs-version'
+    label: 'GitHub Docs: Specifying the Node.js version in setup-node'

package/errors/runner-environment/setup-java-temurin-java8-arm64-not-available.yml

@@ -0,0 +1,93 @@
+id: runner-environment-163
+title: 'actions/setup-java Temurin distribution has no Java 8 builds for macOS ARM64 runners'
+category: runner-environment
+severity: error
+tags:
+  - setup-java
+  - temurin
+  - java-8
+  - arm64
+  - macos-14
+  - macos-15
+  - apple-silicon
+  - adoptium
+patterns:
+  - regex: 'No matching distribution found for Java version 8.*Temurin'
+    flags: 'i'
+  - regex: 'Downloading Java 8.*Temurin.*aarch64.*Error'
+    flags: 'i'
+  - regex: 'Error: No matching distribution found for'
+    flags: 'i'
+  - regex: 'Could not find satisfied version for SemVer.*8.*temurin'
+    flags: 'i'
+error_messages:
+  - 'Error: No matching distribution found for Java version 8 and distribution Temurin'
+  - 'Downloading Java 8 (Temurin) aarch64... Not Found'
+  - 'Could not find satisfied version for SemVer 8 using temurin on darwin aarch64'
+root_cause: |
+  Eclipse Temurin (the continuation of AdoptOpenJDK) does not publish Java 8
+  (JDK 1.8) builds for macOS ARM64 (Apple Silicon / aarch64). Java 8 reached
+  end-of-life for Temurin production support, and no ARM64 macOS binaries were
+  ever released for that version.
+
+  The macos-14 and macos-15 GitHub-hosted runners use ARM64 hardware (M-series
+  chips). When a workflow specifies distribution: temurin with java-version: '8',
+  actions/setup-java cannot find a compatible download and fails. The error is
+  surprising because the identical workflow succeeds on macos-13 (Intel x86_64)
+  where Temurin Java 8 builds do exist.
+
+  This manifests when teams migrate from macos-13 to macos-14/15 for performance
+  or cost reasons without first auditing whether their Java version is supported
+  on ARM64.
+fix: |
+  Preferred: Upgrade to Java 11, 17, or 21 LTS — all of which have Temurin
+  ARM64 macOS builds. If Java 8 is strictly required for the build, use the
+  Zulu distribution (Azul), which publishes Java 8 builds for macOS ARM64.
+  As a last resort, use macos-13 (Intel) for legacy Java 8 jobs.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to Java 17 LTS with Temurin (recommended)'
+    code: |
+      - name: Setup Java 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'   # Temurin supports ARM64 for Java 11, 17, 21
+  - language: yaml
+    label: 'Use Zulu distribution for Java 8 on ARM64 (workaround)'
+    code: |
+      - name: Setup Java 8 via Zulu (ARM64-compatible)
+        uses: actions/setup-java@v4
+        with:
+          distribution: zulu    # Azul Zulu provides Java 8 for macOS ARM64
+          java-version: '8'
+  - language: yaml
+    label: 'Matrix build — Java 8 on Intel, Java 17 on ARM64'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              include:
+                - runner: macos-13     # Intel — Temurin Java 8 available
+                  java: '8'
+                - runner: macos-15     # ARM64 — Temurin Java 17 only
+                  java: '17'
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/setup-java@v4
+              with:
+                distribution: temurin
+                java-version: ${{ matrix.java }}
+prevention:
+  - 'Upgrade to Java 11, 17, or 21 LTS — Java 8 is past EOL for Temurin and has no ARM64 macOS builds'
+  - 'When migrating from macos-13 (Intel) to macos-14/15 (ARM64), audit all Java version requirements first'
+  - 'Use the Zulu distribution as a drop-in replacement for Java 8 when ARM64 support is required'
+  - 'Check Adoptium release availability at adoptium.net/temurin/releases before assuming a version exists on your target platform'
+docs:
+  - url: 'https://adoptium.net/temurin/releases/?version=8&os=mac&arch=aarch64'
+    label: 'Eclipse Temurin releases — Java 8 macOS AArch64 availability'
+  - url: 'https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#supported-distributions'
+    label: 'actions/setup-java: Supported distributions and platforms'
+  - url: 'https://endoflife.date/eclipse-temurin'
+    label: 'Eclipse Temurin end-of-life dates'

package/errors/runner-environment/ubuntu-tzdata-apt-hang-noninteractive-required.yml

@@ -0,0 +1,84 @@
+id: runner-environment-160
+title: 'ubuntu-24.04 apt-get install hangs on tzdata interactive timezone prompt'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - apt-get
+  - tzdata
+  - noninteractive
+  - hang
+  - debian-frontend
+patterns:
+  - regex: 'Please select the geographic area in which you live'
+    flags: 'i'
+  - regex: 'Configuring tzdata'
+    flags: 'i'
+  - regex: 'debconf: unable to initialize frontend: Dialog'
+    flags: 'i'
+error_messages:
+  - 'Please select the geographic area in which you live.'
+  - 'Configuring tzdata'
+  - 'debconf: unable to initialize frontend: Dialog'
+  - 'debconf: falling back to frontend: Readline'
+root_cause: |
+  When installing packages that depend on tzdata (tzdata itself, libssl-dev, php,
+  libpq-dev, and many others) without setting DEBIAN_FRONTEND=noninteractive,
+  apt-get sends interactive prompts for timezone configuration to the TTY. GitHub
+  Actions runner steps have no interactive TTY to respond to debconf prompts, so
+  the step hangs indefinitely until the 6-hour job timeout is reached.
+
+  Ubuntu 24.04 runners are particularly susceptible because the debconf default
+  frontend is "dialog", which requires a terminal. The hang appears to come from
+  a frozen step with no output — making it look like a performance issue rather
+  than a prompt waiting for input.
+
+  The symptom is often indirect: a workflow step that installs a package with
+  tzdata as a transitive dependency (not an explicitly installed package) silently
+  hangs. Developers are surprised because the same apt-get install command works
+  fine in an interactive shell.
+fix: |
+  Set DEBIAN_FRONTEND=noninteractive in the step or job env block before running
+  apt-get install. For tzdata specifically, pre-configure the timezone using
+  environment variables or a symlink before installation.
+fix_code:
+  - language: yaml
+    label: 'Set DEBIAN_FRONTEND at step level'
+    code: |
+      - name: Install dependencies
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y tzdata libssl-dev
+  - language: yaml
+    label: 'Set DEBIAN_FRONTEND at job level (applies to all steps)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          env:
+            DEBIAN_FRONTEND: noninteractive
+          steps:
+            - name: Install dependencies
+              run: |
+                sudo apt-get update
+                sudo apt-get install -y tzdata
+  - language: yaml
+    label: 'Pre-configure timezone to avoid the prompt entirely'
+    code: |
+      - name: Install tzdata non-interactively
+        run: |
+          sudo ln -snf /usr/share/zoneinfo/UTC /etc/localtime
+          echo UTC | sudo tee /etc/timezone
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata
+prevention:
+  - 'Always set DEBIAN_FRONTEND=noninteractive when running apt-get in CI environments'
+  - 'Set DEBIAN_FRONTEND at the job level env block to protect all steps automatically'
+  - 'Check transitive dependencies with apt-cache show <package> to detect tzdata deps early'
+  - 'Add a timeout-minutes to critical steps so tzdata hangs fail fast instead of blocking for 6 hours'
+docs:
+  - url: 'https://manpages.ubuntu.com/manpages/noble/man7/debconf.7.html'
+    label: 'debconf manual page — debconf frontends and noninteractive mode'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Actions: Store information in variables'

package/errors/silent-failures/silent-failures-087.yml

@@ -0,0 +1,120 @@
+id: silent-failures-087
+title: '`fail-fast: false` Does Not Prevent Downstream `needs:` Jobs From Being Skipped When Matrix Jobs Fail'
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - fail-fast
+  - needs
+  - downstream-job
+  - skipped
+  - strategy
+patterns:
+  - regex: 'fail-fast\s*:\s*false'
+    flags: 'i'
+  - regex: 'needs\s*:.*matrix|matrix.*needs\s*:'
+    flags: 'im'
+error_messages:
+  - "This job was skipped"
+  - "Job 'X' is skipped because all dependencies failed or were skipped"
+root_cause: |
+  `strategy.fail-fast: false` only prevents other MATRIX jobs from being
+  cancelled when one matrix job fails. It does NOT affect how downstream
+  jobs that `needs:` the matrix job handle the overall result.
+
+  When at least one matrix job fails (even with `fail-fast: false` allowing
+  all others to complete), the `needs.<matrix-job>.result` for the downstream
+  job evaluates to `'failure'`. A downstream job with a standard `needs:`
+  dependency is then SKIPPED — not because of `fail-fast`, but because its
+  dependency is in a failed state.
+
+  This surprises developers who add `fail-fast: false` expecting the entire
+  pipeline to continue running end-to-end. The final summary/report job
+  that needs the matrix job is silently skipped, producing no output.
+fix: |
+  Add `if: always()` to downstream jobs that should run regardless of matrix
+  outcome. Then explicitly check `needs.<job>.result` values to determine
+  pass/fail:
+
+  - `if: always()` ensures the job is never skipped due to upstream failure
+  - Check `contains(needs.*.result, 'failure')` to detect any matrix failure
+  - Use `needs.<job>.result == 'success'` for strict pass gates
+fix_code:
+  - language: yaml
+    label: "WRONG — summary job silently skipped when matrix job fails"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false  # ❌ allows all matrix jobs to run, but...
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        summary:
+          needs: test           # ❌ still skipped if any matrix job failed
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "All tests done"
+  - language: yaml
+    label: "RIGHT — use if: always() and check result explicitly"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        summary:
+          needs: test
+          if: always()          # ✅ runs even when test jobs failed
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check matrix results
+              if: contains(needs.test.result, 'failure')
+              run: |
+                echo "One or more matrix jobs failed"
+                exit 1
+            - name: Success
+              run: echo "All matrix jobs passed"
+  - language: yaml
+    label: "RIGHT — gate final deploy only when all matrix jobs pass"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          outputs:
+            result: ${{ job.status }}
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          if: always() && needs.test.result == 'success'  # ✅ explicit success check
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+prevention:
+  - "Always add `if: always()` to aggregation/summary/deploy jobs that need to run after a matrix job."
+  - "Explicitly check `needs.<job>.result` or `contains(needs.*.result, 'failure')` rather than relying on implicit pass-through."
+  - "Understand that `fail-fast: false` is matrix-scoped — it does not change how the `needs:` graph handles failures."
+  - "Use job outputs combined with `if: always()` to build robust reporting jobs that capture all matrix outcomes."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow#defining-prerequisite-jobs"
+    label: "Defining prerequisite jobs — needs context and result values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast"
+    label: "workflow syntax — jobs.<job_id>.strategy.fail-fast"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "Status check functions — always(), success(), failure()"
+  - url: "https://github.com/orgs/community/discussions/26822"
+    label: "GitHub Community — fail-fast: false but summary job still skipped"

package/package.json

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