@htekdev/actions-debugger 1.0.116 → 1.0.118

package/errors/caching-artifacts/cache-key-windows-path-separator-never-matches.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-068
+title: '`actions/cache` key containing Windows backslash path separators never matches on restore — cache miss every run'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - windows
+  - path-separator
+  - backslash
+  - cache-miss
+  - cross-platform
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: 'i'
+  - regex: 'cache.*miss.*windows|windows.*cache.*miss'
+    flags: 'i'
+error_messages:
+  - 'Cache not found for input keys:'
+  - 'cache hit for key: false'
+root_cause: |
+  GitHub Actions cache keys are plain strings matched byte-for-byte. On Windows
+  runners, several common patterns produce cache keys containing backslashes (`\`):
+
+    1. Embedding ${{ runner.temp }} or ${{ github.workspace }} directly in the key:
+         key: ${{ runner.os }}-${{ runner.temp }}-${{ hashFiles('**/package-lock.json') }}
+       On Windows, runner.temp resolves to `D:\a\_temp` producing a key with `\`.
+
+    2. Using hashFiles() with backslash glob patterns:
+         key: ${{ hashFiles('**\node_modules\**') }}
+       hashFiles() on Windows sometimes receives backslash-escaped paths in its
+       argument, encoding them into the resulting hash string.
+
+    3. String concatenation with Windows path variables set in earlier steps:
+         TOOL_PATH: C:\hostedtoolcache\node\18\x64
+       When $TOOL_PATH is embedded in the cache key, the `\` chars are literal.
+
+  The cache service stores and retrieves keys as exact string matches. A cache
+  saved with key `npm-D:\a\_temp-abc123` is never found by a lookup for
+  `npm-D:/a/_temp-abc123` or by a lookup on a different run where the runner.temp
+  path differs.
+
+  On Linux/macOS runners, paths always use `/` so this issue is Windows-specific.
+  Cross-platform matrix workflows are especially affected: the Linux cache is found
+  on restore; the Windows cache is always missed.
+fix: |
+  Normalize all path separators to forward slashes before including in cache keys.
+
+  Option 1 — Avoid runner.temp and github.workspace in cache keys entirely.
+  Use runner.os and a fixed path pattern instead:
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+  Option 2 — If you must embed a path, normalize in a prior step:
+    - name: Set normalized cache path
+      shell: bash
+      run: echo "CACHE_PATH=$(echo '${{ runner.temp }}' | tr '\\' '/')" >> $GITHUB_ENV
+    Then:
+    key: ${{ runner.os }}-${{ env.CACHE_PATH }}-${{ hashFiles(...) }}
+
+  Option 3 — Always use forward-slash glob patterns in hashFiles():
+    key: ${{ hashFiles('**/package-lock.json') }}    # correct
+    # NOT: ${{ hashFiles('**\package-lock.json') }}  # Windows-style — avoid
+
+  Option 4 — Use a bash shell step to compute the key and store in GITHUB_ENV,
+  ensuring all path manipulation happens in a POSIX shell that normalizes separators.
+fix_code:
+  - language: yaml
+    label: 'Bad: runner.temp in cache key produces backslashes on Windows'
+    code: |
+      # ❌ runner.temp on Windows = "D:\a\_temp" — backslashes in key → never matches
+      - uses: actions/cache@v4
+        with:
+          path: ${{ runner.temp }}/cache
+          key: ${{ runner.os }}-${{ runner.temp }}-${{ hashFiles('**/lock.json') }}
+  - language: yaml
+    label: 'Good: use runner.os and a fixed path — no path variables in key'
+    code: |
+      # ✅ No Windows path separators in key
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: 'Good: normalize path separators with bash tr before embedding in key'
+    code: |
+      - name: Normalize cache path
+        shell: bash
+        run: |
+          NORM_PATH=$(echo '${{ runner.tool_cache }}' | tr '\\' '/')
+          echo "NORM_TOOL_CACHE=$NORM_PATH" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ runner.tool_cache }}
+          key: ${{ runner.os }}-tools-${{ env.NORM_TOOL_CACHE }}-${{ hashFiles('**/tool-versions') }}
+prevention:
+  - 'Never include runner.temp, runner.tool_cache, or github.workspace in cache keys — these resolve to OS-specific paths with backslashes on Windows'
+  - 'Always use runner.os (e.g., "Windows") as the OS discriminator in cross-platform cache keys, not path-based variables'
+  - 'Use forward-slash glob patterns in hashFiles() expressions on all platforms'
+  - 'When path variables must appear in a cache key, normalize separators to forward slashes in a bash step first and use the env variable'
+  - 'Test cache hit rate explicitly in CI by checking the cache-hit output of the restore step on Windows runners'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/cache/issues/671'
+    label: 'actions/cache#671: Cache key with Windows path separators causes cache miss'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables'
+    label: 'GitHub Docs: Default environment variables (runner.temp, etc.)'

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

@@ -0,0 +1,133 @@
+id: caching-artifacts-069
+title: 'actions/cache save@v5 "Unable to Reserve Cache" When Key Already Exists for Same Branch'
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - cache-save
+  - v5
+  - immutable
+  - key-exists
+  - save-only
+  - reserve-cache
+patterns:
+  - regex: 'Unable to reserve cache with key .+, another job may be creating this cache'
+    flags: 'i'
+  - regex: 'More Details: Key already reserved duplicate'
+    flags: 'i'
+  - regex: 'Failed to save: Unable to reserve cache'
+    flags: 'i'
+error_messages:
+  - 'Failed to save: Unable to reserve cache with key my-cache-key, another job may be creating this cache.'
+  - 'Warning: Cache save failed.'
+  - 'More Details: Key already reserved duplicate'
+root_cause: |
+  GitHub's cache service is write-once per key+branch combination. Once a cache entry
+  has been successfully written for a given key on a given branch/ref, that key cannot
+  be overwritten. The slot is permanently "reserved" by the first writer.
+
+  When using `actions/cache/save@v5` (the standalone save action, separate from the
+  combined restore+save `actions/cache@v5`), the action does NOT automatically skip the
+  save if an exact cache key match already exists. It attempts to write the cache, the
+  service returns "Key already reserved duplicate" (v5 API uses proper JSON errors
+  unlike v3/v4 which returned HTML DOCTYPE responses), and the action emits:
+    "Failed to save: Unable to reserve cache with key X, another job may be creating this cache."
+    "Warning: Cache save failed."
+
+  This differs from the combined `actions/cache@v5` which checks the CACHE_HIT output
+  from its restore step and automatically skips the save on an exact key match. When
+  using the split restore/save pattern (actions/cache/restore + actions/cache/save),
+  the save action has no restore step context, so it always attempts to write —
+  triggering this warning when the key already exists from a previous workflow run.
+
+  Common trigger scenarios:
+  - Using actions/cache/save@v5 in an always() post step to save a cache built during
+    the job, on the second+ run of the same workflow on the same branch
+  - Using @actions/cache npm package's saveCache() directly without first checking
+    whether the key was already restored (restoreCache returned an exact match)
+  - Parallel jobs on the same branch all attempting to save under the same static key
+fix: |
+  Option 1 (recommended): Gate the save step on cache-miss.
+  Use actions/cache/restore@v5 first and only run the save step when the primary key
+  was not an exact hit:
+
+    - name: Restore cache
+      id: restore
+      uses: actions/cache/restore@v5
+      with:
+        key: ${{ env.CACHE_KEY }}
+        path: ~/.cache/my-tool
+
+    - name: Build
+      run: make build
+
+    - name: Save cache
+      if: steps.restore.outputs.cache-hit != 'true'
+      uses: actions/cache/save@v5
+      with:
+        key: ${{ env.CACHE_KEY }}
+        path: ~/.cache/my-tool
+
+  Option 2: Use the combined actions/cache@v5 which handles this automatically.
+
+  Option 3 (programmatic): If using @actions/cache npm package, check restoreCache
+  return value before calling saveCache — skip save if the return value matches the
+  primary key (exact hit).
+fix_code:
+  - language: yaml
+    label: 'Option 1 — gate save on cache-miss from restore step'
+    code: |
+      steps:
+        - name: Restore cache
+          id: cache-restore
+          uses: actions/cache/restore@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            restore-keys: |
+              ${{ runner.os }}-build-
+            path: |
+              ~/.cache/my-tool
+              node_modules
+
+        - name: Build
+          run: make all
+
+        # Only save when the primary key was not an exact hit
+        - name: Save cache
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          uses: actions/cache/save@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            path: |
+              ~/.cache/my-tool
+              node_modules
+  - language: yaml
+    label: 'Option 2 — use combined cache action (auto-skips save on exact hit)'
+    code: |
+      steps:
+        - name: Cache dependencies
+          uses: actions/cache@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            restore-keys: |
+              ${{ runner.os }}-build-
+            path: |
+              ~/.cache/my-tool
+              node_modules
+prevention:
+  - 'Prefer the combined actions/cache@v5 over split restore/save when the primary key
+    is static or content-hash-based — the combined action skips save on exact hit automatically'
+  - 'When using split restore/save, always gate the save step with
+    if: steps.<restore-id>.outputs.cache-hit != ''true'''
+  - 'Never treat "Warning: Cache save failed." as a hard error when using static cache keys
+    across repeated runs — add continue-on-error: true to the save step if the warning
+    is expected and the restored cache is already valid'
+  - 'For programmatic use via @actions/cache npm package, check the return value of
+    restoreCache() before calling saveCache() — skip save when result === primaryKey'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1707'
+    label: 'actions/cache#1707 — Unable to reserve cache (actions/cache/save@v5)'
+  - url: 'https://github.com/actions/cache/tree/main/save#readme'
+    label: 'actions/cache save action README — Case 1: reuse key as-is'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs — Caching dependencies to speed up workflows'

package/errors/concurrency-timing/rerun-failed-jobs-bypasses-concurrency-group.yml

@@ -0,0 +1,89 @@
+id: concurrency-timing-054
+title: '"Re-run failed jobs" bypasses concurrency group — runs in parallel with a newly triggered run for the same group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - rerun
+  - re-run-failed-jobs
+  - parallel
+  - cancel-in-progress
+patterns:
+  - regex: 'Re-run failed jobs'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+root_cause: |
+  When a developer clicks "Re-run failed jobs" (as opposed to "Re-run all jobs"),
+  GitHub Actions does not evaluate the workflow's concurrency group before starting
+  the rerun. The rerun begins immediately and runs in parallel with any currently
+  in-progress or newly triggered run that occupies the same concurrency group.
+
+  This is distinct from "Re-run all jobs", which DOES re-trigger the concurrency
+  check and will cancel the currently in-progress run if cancel-in-progress is true,
+  or queue behind it if cancel-in-progress is false.
+
+  Common scenario:
+    1. A push triggers run A, which starts and partially fails.
+    2. A second push triggers run B for the same branch (same concurrency group).
+       Run B is queued or cancels run A depending on cancel-in-progress setting.
+    3. Developer hits "Re-run failed jobs" on run A.
+    4. Run A's rerun starts immediately — now run A (rerun) and run B are both
+       executing concurrently, violating the intent of the concurrency group.
+
+  Side effects:
+    - Two deploys to the same environment can run simultaneously.
+    - A self-hosted runner with a single slot gets double-booked.
+    - Race conditions between two concurrent jobs writing to the same artifact.
+
+  Root cause: GitHub's "Re-run failed jobs" path was implemented as a targeted job
+  restart that bypasses workflow-level orchestration including concurrency evaluation.
+  This behavior is tracked in actions/runner#2294 (open).
+fix: |
+  Option 1 — Use "Re-run all jobs" instead of "Re-run failed jobs" when the workflow
+  has a concurrency group. "Re-run all jobs" triggers a fresh run that participates
+  in concurrency evaluation normally.
+
+  Option 2 — Include github.run_attempt in the concurrency group key so each attempt
+  gets its own group slot, preventing cancellation loops during reruns while still
+  serializing independent triggers:
+    group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_attempt }}
+    cancel-in-progress: false
+
+  Option 3 — For deployment workflows, use environment protection rules as the
+  serialization mechanism instead of (or in addition to) concurrency groups. A
+  pending environment review gate serializes deployments even when concurrency is
+  bypassed.
+
+  Option 4 — Accept the behavior: if the failed jobs don't interact with shared
+  resources, concurrent partial reruns may be safe. Restrict "Re-run failed jobs" to
+  jobs that are idempotent and isolated.
+fix_code:
+  - language: yaml
+    label: 'Option A: include run_attempt in group key — each attempt gets its own slot'
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_attempt }}
+        cancel-in-progress: false
+  - language: yaml
+    label: 'Option B: environment protection to serialize deployments independent of concurrency'
+    code: |
+      jobs:
+        deploy:
+          environment: production   # Requires reviewer approval; serializes even without concurrency
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - 'Prefer "Re-run all jobs" over "Re-run failed jobs" when your workflow uses a concurrency group to prevent duplicate concurrent runs'
+  - 'Include ${{ github.run_attempt }} in the concurrency group key to give each attempt its own slot and avoid silent bypass'
+  - 'For deployment workflows with shared infrastructure, combine concurrency groups with environment protection rules for defense-in-depth serialization'
+  - 'Document in your workflow YAML that "Re-run failed jobs" bypasses concurrency to alert future maintainers'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://github.com/actions/runner/issues/2294'
+    label: 'actions/runner#2294: Re-run failed jobs bypasses concurrency group (open)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs'
+    label: 'GitHub Docs: Re-running workflows and jobs'

package/errors/concurrency-timing/workflow-run-head-branch-null-schedule-dispatch-concurrency.yml

@@ -0,0 +1,135 @@
+id: concurrency-timing-055
+title: '`github.event.workflow_run.head_branch` is null for `schedule`- and `workflow_dispatch`-triggered
+  parent workflows — concurrency group key collapses all downstream runs into one slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - workflow_run
+  - concurrency
+  - head_branch
+  - schedule
+  - null-key
+  - deployment
+patterns:
+  - regex: 'on:\s+workflow_run:'
+    flags: 'si'
+  - regex: 'group:.*event\.workflow_run\.head_branch'
+    flags: 'i'
+error_messages:
+  - "Canceling since a higher priority waiting run was found for the same concurrency group"
+  - "This run has been cancelled. Concurrency group: deploy-"
+root_cause: |
+  `github.event.workflow_run.head_branch` is null/empty when the triggering (upstream)
+  workflow was itself triggered by `schedule`, `workflow_dispatch`, `repository_dispatch`,
+  or any other non-branch event. Only workflows triggered by branch-based events (push,
+  pull_request, etc.) produce a non-null head_branch value.
+
+  The standard recommendation for workflow_run-triggered workflows (see also
+  concurrency-timing-045) is to key the concurrency group on head_branch:
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+
+  For branch-based parent triggers this works correctly. For schedule- or
+  workflow_dispatch-triggered parent workflows, head_branch is null, making the
+  concurrency group key evaluate to `deploy-` (empty suffix). Every downstream run
+  where the parent was triggered by schedule or dispatch shares the SAME concurrency
+  slot. The second scheduled downstream run cancels the first — silently, because
+  `${{ null }}` evaluates to an empty string in GitHub Actions expressions with no
+  warning or error.
+
+  This is commonly introduced when teams follow a deploy-after-CI pattern where the
+  nightly build (schedule) triggers a downstream deploy/notify workflow_run workflow
+  and copy the branch-scoped concurrency pattern from another workflow.
+fix: |
+  Add a fallback value to handle null head_branch, or use a more robust key.
+
+  Option 1 — head_branch with workflow_run.id fallback (recommended):
+    Use head_branch when available (branch-based parent) and fall back to the unique
+    workflow_run id (schedule/dispatch parent) to guarantee no cross-run collisions.
+
+  Option 2 — workflow_run.id only:
+    If the workflow_run-triggered downstream workflow is exclusively for non-branch
+    parents (schedule, dispatch), key the group on github.event.workflow_run.id.
+    Every downstream run gets its own unique slot.
+
+  Option 3 — Restrict trigger with branches: filter:
+    Limit the workflow_run trigger to branch-based parent runs using `branches:`.
+    Schedule/dispatch-triggered completions are silently ignored so there is no
+    concurrency collision to manage.
+fix_code:
+  - language: yaml
+    label: 'WRONG — head_branch is null for schedule-triggered parents; all runs share one slot'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["Nightly Build"]
+          types: [completed]
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'RIGHT — fallback to workflow_run.id prevents slot collision for schedule parents'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["Nightly Build"]
+          types: [completed]
+
+      # head_branch is populated for push/pull_request-triggered parents
+      # workflow_run.id is always unique — prevents cross-run collision for schedule/dispatch parents
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch || github.event.workflow_run.id }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying commit ${{ github.event.workflow_run.head_sha }}"
+  - language: yaml
+    label: 'RIGHT — restrict workflow_run to branch-based parents only'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main, 'release/**']
+          # schedule- and workflow_dispatch-triggered parent completions have no branch;
+          # the branches: filter excludes them, so no null head_branch issue
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying branch ${{ github.event.workflow_run.head_branch }}"
+prevention:
+  - 'Always check whether parent workflows may be triggered by schedule or workflow_dispatch before
+    keying a workflow_run downstream concurrency group on head_branch.'
+  - 'Add a || fallback for any workflow_run context property that may be null — head_branch, head_sha,
+    and pull_requests are null for schedule/dispatch-triggered parents.'
+  - 'Add a debug step that echoes github.event.workflow_run.head_branch early in the workflow to verify
+    it is populated for all expected parent trigger types during initial rollout.'
+  - 'Use branches: on the workflow_run trigger to restrict to branch-based events if schedule/dispatch
+    parent completions do not need to be handled.'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_run'
+    label: 'GitHub Webhook Docs: workflow_run payload — head_branch property'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event trigger'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'

package/errors/known-unsolved/empty-matrix-fromjson-workflow-failure-no-conditional-skip.yml

@@ -0,0 +1,108 @@
+id: known-unsolved-064
+title: 'No conditional matrix skip — an empty matrix from `fromJSON([])` always fails the workflow with a validation error'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - dynamic-matrix
+  - fromJSON
+  - conditional
+  - strategy
+  - limitation
+patterns:
+  - regex: 'The strategy/matrix must contain at least one'
+    flags: 'i'
+  - regex: 'matrix must define at least one vector'
+    flags: 'i'
+  - regex: 'Error when evaluating .strategy. for job.*matrix.*empty'
+    flags: 'i'
+error_messages:
+  - 'The strategy/matrix must contain at least one vector'
+  - 'matrix must define at least one vector'
+  - 'Error when evaluating ''strategy'' for job'
+root_cause: |
+  GitHub Actions validates that a matrix strategy always produces at least one job.
+  When a prior step outputs an empty JSON array and the matrix job uses
+  `fromJSON(steps.generate.outputs.matrix)`, the workflow fails at plan time with
+  a validation error before any jobs run.
+
+  There is NO supported way to:
+    - Provide an `if:` condition on the matrix strategy to skip it entirely
+    - Use `strategy: if: ${{ condition }}` syntax (does not exist)
+    - Have a job run zero times when its matrix is empty
+
+  This is a fundamental platform limitation: matrix jobs must always expand to at
+  least one job instance. The validation runs before job execution, so even an `if:`
+  on the job itself does not help — the matrix must be non-empty regardless.
+
+  Common scenarios:
+    - CI that builds only changed packages: if no packages changed, the matrix
+      is empty and the entire workflow fails.
+    - Release workflows that conditionally matrix over artifacts: if nothing was
+      built, the matrix is empty.
+    - PR labeler workflows that matrix over affected services: a trivial change
+      affects no services, producing an empty list.
+
+  Note: yaml-syntax-008 covers the technical "fromJSON parse error" message. This
+  entry covers the LIMITATION: there is no native mechanism to conditionally skip
+  matrix jobs or provide a zero-matrix strategy.
+fix: |
+  Workaround 1 — Always include at least one sentinel/dummy entry and guard with if:
+    In the matrix-generating step, append a sentinel entry when the list is empty:
+      matrix=$(echo "$matrix" | jq 'if length == 0 then [{"skip":true}] else map(. + {"skip":false}) end')
+    Then in the job:
+      if: ${{ !matrix.skip }}
+
+  Workaround 2 — Use a separate check job with needs: to gate the matrix job:
+    Add an upstream job that outputs a boolean "has_work". The matrix job then uses
+    `needs: check` and reads `needs.check.outputs.has_work` in an `if:` condition.
+    This still requires the matrix to be non-empty (use sentinel), but the `if:`
+    prevents actual work from running.
+
+  Workaround 3 — Always include a no-op entry in the matrix output:
+    Ensure the matrix-generating script never outputs an empty array by always
+    appending a `{"target":"none"}` entry, then:
+      if: matrix.target != 'none'
+
+  None of these workarounds are elegant. This is a known limitation with no native
+  fix scheduled. Tracked in actions/runner#1502 (96+ reactions, open since 2021).
+fix_code:
+  - language: yaml
+    label: 'Workaround: inject sentinel entry when matrix is empty, skip in job if:'
+    code: |
+      jobs:
+        generate-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.set-matrix.outputs.matrix }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Build your matrix list; inject sentinel when empty
+                matrix='[]'  # Replace with real generation logic
+                if [ "$(echo "$matrix" | jq 'length')" -eq 0 ]; then
+                  matrix='[{"target":"__skip__"}]'
+                fi
+                echo "matrix=$matrix" >> $GITHUB_OUTPUT
+
+        build:
+          needs: generate-matrix
+          if: ${{ fromJSON(needs.generate-matrix.outputs.matrix)[0].target != '__skip__' }}
+          strategy:
+            matrix:
+              include: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building ${{ matrix.target }}"
+prevention:
+  - 'Never pass a potentially empty array directly to fromJSON() in a matrix strategy — always guard with a sentinel entry'
+  - 'Add an upstream check job that validates matrix size before the matrix job runs'
+  - 'Document the sentinel pattern in your workflow so future maintainers understand why a dummy entry exists'
+  - 'Vote/watch actions/runner#1502 for native conditional matrix support'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow'
+    label: 'GitHub Docs: Running variations of jobs in a workflow (matrix)'
+  - url: 'https://github.com/actions/runner/issues/1502'
+    label: 'actions/runner#1502: Support for empty matrix (96+ reactions, open)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix'
+    label: 'GitHub Docs: jobs.<job_id>.strategy.matrix'