@htekdev/actions-debugger 1.0.131 → 1.0.133

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

@@ -0,0 +1,100 @@
+id: caching-artifacts-078
+title: '`upload-artifact/merge` aborts with "Failed to DeleteArtifact: (404) Not Found" when a delete is retried after a transient server error'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - merge
+  - delete-merged
+  - 404
+  - idempotent-delete
+  - artifact-merge
+patterns:
+  - regex: 'Failed to DeleteArtifact.*non-retryable error.*404|DeleteArtifact.*404.*Not Found'
+    flags: 'i'
+  - regex: 'Received non-retryable error.*Failed request.*404.*artifact not found'
+    flags: 'i'
+error_messages:
+  - "Error: Failed to DeleteArtifact: Received non-retryable error: Failed request: (404) Not Found: artifact not found"
+  - "Attempt 1 of 5 failed with error: Unexpected token '<', \"<!DOCTYPE \"... is not valid JSON. Retrying request in 3000 ms..."
+root_cause: |
+  When using `actions/upload-artifact/merge@v6` (or later) with `delete-merged: true`,
+  the action deletes each source artifact after merging them into the combined artifact.
+  If a delete request encounters a transient server error (e.g., a malformed HTML response
+  instead of JSON — indicated by "Unexpected token '<'"), the action retries the delete.
+
+  If the first delete request was actually processed by the server before the error was
+  returned to the client, the artifact is already gone. The retry then receives a 404
+  Not Found, which `DeleteArtifact` treats as a **non-retryable fatal error** and
+  immediately aborts the job.
+
+  Because `delete-merged: true` is destructive — source artifacts have already been
+  deleted by this point — retrying the entire job from scratch is impossible, as the
+  source artifacts no longer exist.
+
+  Root bug: `DeleteArtifact` should treat 404 as a success (idempotent delete — the
+  artifact not existing IS the desired state). This is tracked in upload-artifact#751
+  (open, Jan 2026). No server-side fix has been released as of June 2026.
+fix: |
+  Option 1 — Add `continue-on-error: true` to the merge step so that the 404 error
+  does not fail the overall job. Verify that the merge artifact was created successfully
+  before relying on this workaround, since `continue-on-error` also swallows real
+  failures.
+
+  Option 2 — Set `delete-merged: false` and handle deletion of source artifacts in a
+  separate step with explicit error handling (e.g., `gh api` with `--fail-with-body` and
+  a conditional step that ignores 404 exit codes).
+
+  Option 3 — Wrap the merge step in a retry loop using `nick-invision/retry` or a
+  shell retry, but note that re-running the merge after partial deletion will fail because
+  source artifacts are gone. Prevention is better than recovery here.
+
+  Monitor upload-artifact#751 for an upstream fix that makes 404 on DeleteArtifact
+  idempotent/non-fatal.
+fix_code:
+  - language: yaml
+    label: 'continue-on-error workaround — prevents 404 from failing the job'
+    code: |
+      - name: Merge artifacts
+        uses: actions/upload-artifact/merge@v6
+        # ⚠️ Workaround: continue-on-error so a DeleteArtifact 404 does not fail the job.
+        # Also swallows real upload failures — add a downstream step to verify the
+        # merged artifact exists if reliability matters.
+        continue-on-error: true
+        with:
+          name: merged-results
+          pattern: partial-results-*
+          delete-merged: true
+  - language: yaml
+    label: 'delete-merged: false with manual deletion that ignores 404'
+    code: |
+      - name: Merge artifacts (no auto-delete)
+        uses: actions/upload-artifact/merge@v6
+        with:
+          name: merged-results
+          pattern: partial-results-*
+          delete-merged: false   # ✅ Suppress automatic deletion
+
+      # Manually delete source artifacts, ignoring 404 responses (already deleted)
+      - name: Delete source artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          for artifact_id in $(gh api repos/${{ github.repository }}/actions/artifacts \
+            --jq '.artifacts[] | select(.name | startswith("partial-results-")) | .id'); do
+            gh api --method DELETE \
+              repos/${{ github.repository }}/actions/artifacts/$artifact_id \
+              --silent || echo "Artifact $artifact_id already deleted (404) — ignoring"
+          done
+prevention:
+  - 'Avoid `delete-merged: true` in critical CI pipelines until upload-artifact#751 is fixed — use manual deletion with 404 tolerance instead'
+  - 'Add `continue-on-error: true` to merge steps as a temporary workaround for the 404 abort'
+  - 'Keep source artifacts available by using `delete-merged: false` until the upstream fix lands'
+  - 'Monitor actions/upload-artifact#751 for a release that treats DeleteArtifact 404 as success'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/751'
+    label: 'upload-artifact#751: DeleteArtifact should not consider a 404 response an error (open, Jan 2026)'
+  - url: 'https://github.com/actions/upload-artifact/blob/main/merge/README.md'
+    label: 'actions/upload-artifact merge action README — delete-merged option'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts'
+    label: 'GitHub Docs: Storing workflow data as artifacts'

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

@@ -0,0 +1,95 @@
+id: caching-artifacts-079
+title: '`setup-node@v5` auto-enables caching when `packageManager` is set in `package.json` — post-run fails with "Path Validation Error" if dependencies are not installed'
+category: caching-artifacts
+severity: error
+tags:
+  - setup-node
+  - caching
+  - packageManager
+  - path-validation
+  - post-run
+  - setup-node-v5
+  - automatic-caching
+patterns:
+  - regex: 'Path Validation Error.*Path.*specified.*action.*caching.*do.*not exist'
+    flags: 'i'
+  - regex: 'Path.*specified.*action.*caching.*do.{0,5}not exist.*no cache'
+    flags: 'i'
+error_messages:
+  - "Error: Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved."
+root_cause: |
+  Starting with `actions/setup-node@v5`, automatic caching is enabled **by default**
+  whenever a `packageManager` field is present in the project's `package.json` file —
+  even if the workflow does not explicitly configure caching via the `cache:` input.
+
+  This means jobs that merely run linting, type-checking, or any step that does not
+  execute `npm install` / `yarn install` / `pnpm install` will still attempt to cache
+  the package manager's dependency directory in the post-run cleanup step. Because no
+  `install` was run, the expected cache paths (e.g., `~/.npm`, `~/.yarn/cache`,
+  `~/.pnpm-store`) do not exist. The toolkit's path validation then emits:
+  "Path Validation Error: Path(s) specified in the action for caching do(es) not exist"
+  and **fails the job step**, turning a previously green run red.
+
+  **Why this surprises developers:**
+  - The workflow never explicitly enables caching — the presence of `packageManager`
+    in `package.json` is the invisible trigger.
+  - The error appears in the **post-run** cleanup step, not in the setup step where
+    caching is configured, making it harder to trace.
+  - Workflows that have always worked (no `cache:` input) start failing after upgrading
+    from `setup-node@v4` to `setup-node@v5`.
+
+  **Resolution:** `setup-node@v6` (released Oct 2025) changed the default so automatic
+  caching only applies to npm; yarn/pnpm caching is now opt-in. Upgrading to v6 or
+  explicitly disabling the cache in v5 resolves the issue.
+  Source: setup-node#1363 (5 reactions, closed Oct 2025 via v6 release).
+fix: |
+  Option 1 (recommended) — Upgrade to `actions/setup-node@v6`. The v6 release limits
+  automatic caching to npm only; yarn and pnpm caching require explicit `cache: yarn`
+  or `cache: pnpm` input.
+
+  Option 2 — Disable automatic caching in v5 by setting `package-manager-cache: false`.
+  Use this if you cannot upgrade to v6 immediately.
+
+  Option 3 — Ensure dependencies are installed in every job that uses `setup-node@v5`.
+  If the job only needs Node for tooling (lint, type-check, etc.), run a minimal
+  `npm ci --ignore-scripts` or equivalent before the setup post-run fires.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to setup-node@v6 — fixes automatic caching defaults'
+    code: |
+      # ✅ Recommended: v6 only auto-caches npm, not yarn/pnpm
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          # No cache: input needed — auto-caching is npm-only in v6
+  - language: yaml
+    label: 'Disable automatic caching in v5 with package-manager-cache: false'
+    code: |
+      # ✅ Workaround for setup-node@v5: suppress auto-caching
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          package-manager-cache: false   # Disables packageManager-triggered auto-cache
+      - run: npx eslint src/
+  - language: yaml
+    label: 'Opt in to caching explicitly for jobs that do install dependencies'
+    code: |
+      # ✅ Jobs that do install: use explicit cache input instead of relying on auto-detect
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'            # Explicit opt-in — cache only when deps are installed
+      - run: npm ci
+      - run: npm test
+prevention:
+  - 'Upgrade to `setup-node@v6` which fixes the over-eager auto-caching of yarn/pnpm in v5'
+  - 'In v5, always set `package-manager-cache: false` for jobs that do not run `install`'
+  - 'Check `package.json` for a `packageManager` field — its presence triggers auto-caching in v5 even without an explicit `cache:` input'
+  - 'Run lint, type-check, and audit jobs without setup-node caching to keep them fast and avoid phantom cache failures'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1363'
+    label: 'setup-node#1363: v5 fails with Path Validation Error in Post Run steps (5 reactions, resolved in v6)'
+  - url: 'https://github.com/actions/setup-node/releases/tag/v6.0.0'
+    label: 'setup-node v6.0.0 release notes — auto-caching limited to npm'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data'
+    label: 'setup-node docs: Caching packages data'

package/errors/concurrency-timing/concurrency-timing-061.yml

@@ -0,0 +1,138 @@
+id: concurrency-timing-061
+title: '`github.workflow` in reusable workflow (`workflow_call`) returns caller''s name — shared concurrency group causes deadlock'
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - reusable-workflow
+  - workflow-call
+  - github-workflow-context
+  - deadlock
+  - concurrency-group
+patterns:
+  - regex: 'Canceling since a deadlock for concurrency group .+ was detected between .+ and .+'
+    flags: 'i'
+  - regex: 'deadlock.*concurrency group.*detected'
+    flags: 'i'
+error_messages:
+  - "Canceling since a deadlock for concurrency group 'CI-refs/heads/main' was detected between 'CI workflow' and 'deploy'"
+  - "Canceling since a deadlock for concurrency group 'test-refs/heads/master' was detected between 'test workflow' and 'deploy'"
+root_cause: |
+  When a caller workflow invokes a reusable workflow via `uses:` (the `workflow_call` trigger),
+  the `github.workflow` context variable inside the CALLEE resolves to the CALLER's workflow
+  name — not the callee's own filename. This is documented behavior but it directly undermines
+  the widely recommended concurrency group pattern of `${{ github.workflow }}-${{ github.ref }}`.
+
+  If both the caller and the callee define:
+  ```yaml
+  concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+  ```
+
+  Both workflows compute the SAME group key (because `github.workflow` is the caller's name in
+  both). GitHub detects that two workflow instances are competing for the same concurrency slot
+  in a way that cannot resolve — one is waiting for the other which is waiting for the first —
+  treats it as a deadlock, and cancels one of the runs.
+
+  **Why this is especially confusing:**
+  The fix recommended for general concurrency group collisions (`${{ github.workflow }}-${{ github.ref }}`)
+  is itself the cause of this deadlock when applied naively to reusable workflows. Teams that
+  copy the "safe" concurrency pattern from caller to callee introduce the bug.
+
+  **Real-world evidence:**
+  - actions/runner#3205: `github.workflow` returns parent workflow name in child workflows
+  - vergil-project/vergil-actions#176: ci-push.yml calls ci.yml via workflow_call; both use
+    `${{ github.workflow }}-${{ github.ref }}`; deadlock detected on every push
+  - github/gh-aw#35173: workflow_call fan-out cancellations due to shared concurrency namespace
+  - SO #78101326 (6 upvotes, 1738 views): "GitHub Actions concurrency deadlock" — 6 answers
+    confirming the root cause is `github.workflow` returning the caller name
+fix: |
+  Use `github.workflow_ref` instead of `github.workflow` in the CALLEE (reusable) workflow.
+  `github.workflow_ref` contains the full workflow file path (e.g.
+  `.github/workflows/deploy.yml@refs/heads/main`), which is unique per callee file and
+  does NOT inherit the caller's name.
+
+  **Preferred approach:** Define concurrency ONLY in the caller workflow and remove it from the
+  callee entirely. The callee runs as part of the caller's run and does not need its own
+  concurrency group. This is the cleanest fix and matches GitHub's recommendations for
+  reusable workflow design.
+
+  **Avoid:** Defining concurrency in both caller and callee with the same expression — this
+  is the root cause of the deadlock regardless of which context variable is used for the group
+  key, unless the keys are guaranteed to differ.
+fix_code:
+  - language: yaml
+    label: 'Callee (reusable workflow): use github.workflow_ref — unique per callee file'
+    code: |
+      # .github/workflows/deploy.yml (callee — reusable workflow)
+      name: Deploy
+
+      on:
+        workflow_call:
+
+      # ✅ github.workflow_ref includes the full path, NOT the caller's name
+      concurrency:
+        group: ${{ github.workflow_ref }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Preferred: define concurrency only in the caller, none in the callee'
+    code: |
+      # .github/workflows/ci.yml (caller workflow)
+      name: CI
+
+      on:
+        push:
+          branches: [main]
+
+      # Concurrency defined only in the caller
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          # ✅ No concurrency block here — the reusable workflow has no concurrency group
+          uses: ./.github/workflows/deploy.yml
+
+      ---
+      # .github/workflows/deploy.yml (callee — reusable workflow)
+      name: Deploy
+
+      on:
+        workflow_call:
+
+      # ✅ No concurrency block — inherit scheduling from caller
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+prevention:
+  - "Never use `github.workflow` in a reusable workflow's concurrency group — it resolves to the caller's name, not the callee's"
+  - "Use `github.workflow_ref` in callee workflows if a concurrency group is truly needed there"
+  - "Prefer defining concurrency only in the caller when calling reusable workflows via `uses:` — keep callee stateless"
+  - "Audit all reusable workflows for concurrency groups that use `github.workflow` and replace with `github.workflow_ref`"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Control the concurrency of workflows and jobs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub Docs: github context — github.workflow_ref field'
+  - url: 'https://github.com/actions/runner/issues/3205'
+    label: 'actions/runner#3205: github.workflow returns parent name in child workflows (closed not_planned)'
+  - url: 'https://stackoverflow.com/questions/78101326/github-actions-concurrency-deadlock'
+    label: 'SO #78101326: GitHub Actions concurrency deadlock in reusable workflows (6 upvotes, 1738 views)'

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

@@ -0,0 +1,142 @@
+id: known-unsolved-076
+title: '`env` context unavailable in `strategy.matrix` — workflow env vars cannot be used in matrix definitions'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - env-context
+  - strategy
+  - fromJSON
+  - dynamic-matrix
+  - context-availability
+  - known-limitation
+patterns:
+  - regex: 'Error when evaluating .+strategy.+ for job'
+    flags: 'i'
+  - regex: 'strategy.*matrix.*\$\{\{.*env\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: .+env.+ \(Line: \d+'
+    flags: 'i'
+error_messages:
+  - "Error when evaluating 'strategy' for job 'build'. .github/workflows/deploy.yaml (Line: 10, Col: 15): Error parsing fromJson"
+  - "Error when evaluating 'strategy' for job 'test'. Input string '3.11' is not a valid number. Path '[0]'"
+  - "Error when evaluating 'strategy' for job 'matrix-job': Object reference not set to an instance of an object"
+root_cause: |
+  The `env` context — workflow-level environment variables defined under the top-level `env:` key
+  — is NOT available during evaluation of `strategy.matrix`. GitHub Actions evaluates the
+  `strategy:` block at workflow QUEUING time, before jobs are dispatched and before environment
+  variable interpolation occurs. Any expression like `${{ env.VERSIONS_JSON }}` or
+  `${{ fromJSON(env.VERSIONS_JSON) }}` inside `strategy.matrix` resolves to an empty string
+  or produces a parse error.
+
+  **GitHub's documented context availability:**
+  Per the official context availability table, `env` is explicitly NOT listed as available in
+  `jobs.<job_id>.strategy`. Available contexts there are only: `github`, `inputs`, `vars`,
+  `needs`, `strategy`, and `matrix`.
+
+  **Common failure patterns:**
+  - Using `${{ fromJSON(env.MY_VERSIONS) }}` to share a JSON array between matrix and other steps
+  - Setting `env: DEPLOY_ENVS: '["staging","production"]'` at workflow level and referencing it
+    in the matrix include/exclude blocks
+  - Using workflow-level env vars to DRY up matrix configs shared with `run:` script logic
+
+  **Why this surprises developers:**
+  - `env` IS available inside `jobs.<job_id>.steps.*` — the limitation is specific to `strategy`
+  - The error message "Error parsing fromJson" doesn't mention that `env` context is unavailable
+  - The empty-string resolution (when no parse error) causes a silent empty matrix, not an error
+
+  Sources: actions/runner#480 (281 👍, open since 2020 — most-upvoted env context limitation);
+  SO#74072206 (10 upvotes, 19,053 views); SO#76039616 (6 upvotes, 10,482 views)
+fix: |
+  Three workarounds exist, in order of preference:
+
+  **Option 1 — Use `vars` context (org/repo-level variables)**
+  Org-level and repo-level variables (`vars.*`) ARE available in `strategy.matrix`.
+  Move shared values to repository Settings → Secrets and variables → Variables instead of
+  workflow-level `env:`.
+
+  **Option 2 — Compute matrix in a previous job's output (most flexible)**
+  Use a dedicated setup job that outputs the matrix JSON, then reference it in dependent
+  jobs via `fromJSON(needs.setup.outputs.matrix)`. This also enables dynamic matrix
+  generation from files, APIs, or scripts.
+
+  **Option 3 — Hardcode values directly in strategy.matrix**
+  Duplicate the values in `strategy.matrix` explicitly. Avoids the DRY violation but
+  is the simplest fix when values rarely change.
+fix_code:
+  - language: yaml
+    label: 'Option 1: Use vars context — repo/org variables ARE available in strategy'
+    code: |
+      # In repo Settings → Secrets and variables → Variables, create:
+      # Name: PYTHON_VERSIONS  Value: ["3.10","3.11","3.12"]
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # ✅ vars context IS available in strategy.matrix
+              python-version: ${{ fromJSON(vars.PYTHON_VERSIONS) }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: python -m pytest
+  - language: yaml
+    label: 'Option 2: Compute matrix in a setup job, pass via needs outputs'
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.set-matrix.outputs.matrix }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Build matrix from any source: env var, file, API, conditional logic
+                echo 'matrix={"python-version":["3.10","3.11","3.12"]}' >> "$GITHUB_OUTPUT"
+
+        test:
+          needs: setup
+          strategy:
+            matrix:
+              # ✅ fromJSON(needs.*.outputs.*) IS available in strategy.matrix
+              ${{ fromJSON(needs.setup.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: python -m pytest
+  - language: yaml
+    label: 'Anti-pattern: env context in strategy.matrix causes parse error'
+    code: |
+      # ❌ Workflow-level env vars are NOT available in strategy.matrix
+
+      env:
+        PYTHON_VERSIONS: '["3.10","3.11","3.12"]'
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # This causes: "Error when evaluating 'strategy' for job 'test'"
+              python-version: ${{ fromJSON(env.PYTHON_VERSIONS) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: python --version
+prevention:
+  - "Use `vars.*` (repo/org variables from Settings) instead of workflow `env:` for values shared between matrix and steps"
+  - "Generate dynamic matrices in a dedicated setup job and pass via `needs.*.outputs.*`"
+  - "Consult the GitHub Actions context availability table before using any context in `strategy` — not all contexts are available there"
+  - "actionlint will flag `env` context usage in strategy blocks — add it to your CI pipeline or pre-commit hooks"
+  - "Remember: `env` IS available in `steps.*.run`, `steps.*.with`, and most other places — the restriction is specific to `strategy` and `concurrency`"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability'
+    label: 'GitHub Docs: Context availability table (env not listed for strategy)'
+  - url: 'https://github.com/actions/runner/issues/480'
+    label: 'actions/runner#480: Workflow level env does not work in all fields (281 upvotes, open since 2020)'
+  - url: 'https://stackoverflow.com/questions/74072206/github-actions-use-variables-in-matrix-definition'
+    label: 'SO #74072206: Use variables in matrix definition (10 upvotes, 19,053 views)'
+  - url: 'https://stackoverflow.com/questions/76039616/how-to-read-in-an-array-of-strings-to-matrix-in-github-actions'
+    label: 'SO #76039616: Read array of strings into matrix (6 upvotes, 10,482 views)'

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

@@ -0,0 +1,140 @@
+id: known-unsolved-077
+title: '`fromJSON()` array nested inside a matrix object does not expand — resolves as literal "Array" or raw JSON string'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - matrix
+  - fromJSON
+  - dynamic-matrix
+  - object
+  - array-expansion
+  - known-limitation
+  - silent-failure
+patterns:
+  - regex: 'fromJSON\(needs\.\w+\.outputs\.'
+    flags: 'i'
+  - regex: 'matrix\.\w+\.\w+.*\bArray\b|\bArray\b.*matrix\.'
+    flags: 'i'
+error_messages:
+  - "echo x86_64 Array"
+  - 'matrix.component.distro = Array'
+  - 'matrix.component.distro = ["el8","el9"]'
+root_cause: |
+  GitHub Actions supports expanding a JSON array into matrix rows when `fromJSON()` is
+  used **at the top level** of a matrix dimension:
+  ```yaml
+  strategy:
+    matrix:
+      version: ${{ fromJSON(needs.setup.outputs.versions) }}  # ✅ expands to N rows
+  ```
+
+  However, when the array is nested inside a matrix **object** (i.e., as a value within
+  one of the items of a matrix dimension), `fromJSON()` does NOT expand it into rows.
+  Instead, the expression resolves to:
+  - The literal string `"Array"` when `fromJSON()` is used (type-1 pattern)
+  - The raw JSON string (e.g., `["el8","el9"]`) when the output is used directly (type-2 pattern)
+
+  **Failing patterns:**
+  ```yaml
+  # Type 1 — fromJSON inside a matrix object value
+  matrix:
+    component:
+      - name: rhel
+        distro: ${{ fromJSON(needs.setup.outputs.rpms) }}   # ❌ becomes "Array"
+
+  # Type 2 — raw JSON string inside a matrix object value
+  matrix:
+    component:
+      - name: rhel
+        distro: ${{ needs.setup.outputs.rpms }}              # ❌ becomes the raw JSON string
+  ```
+
+  The expansion mechanism only applies when the entire matrix dimension value is a
+  `fromJSON()` call returning an array. Nesting breaks the expansion because the runner
+  evaluates the object first and cannot retroactively fan out a single object item into
+  multiple rows.
+
+  This is a documented limitation. GitHub's matrix engine does not support nested array
+  expansion within object-typed matrix dimensions. The issue is tracked in
+  actions/runner#3794 (open since Apr 2025, no planned fix).
+
+  **Why this is confusing:**
+  The `fromJSON()` approach works perfectly when the array IS the entire dimension:
+  `matrix: version: ${{ fromJSON(needs.setup.outputs.versions) }}`. Developers naturally
+  try to reuse the same pattern inside object dimensions and get silently wrong values —
+  the job runs to completion but with a single row containing "Array" instead of N rows.
+fix: |
+  Restructure the matrix so that the dynamic array is the TOP-LEVEL matrix dimension,
+  not nested inside an object. Move any additional object properties into the
+  `matrix.include` block to pair them with each array element.
+
+  If you need multiple outputs to compose a matrix, pre-process them into a combined
+  JSON array in an upstream job step and pass the combined output as a single
+  `fromJSON()` expression.
+fix_code:
+  - language: yaml
+    label: 'Move the dynamic array to the top-level dimension — this expands correctly'
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          outputs:
+            rpms: ${{ steps.distros.outputs.rpms }}
+            debs: ${{ steps.distros.outputs.debs }}
+          steps:
+            - id: distros
+              run: |
+                echo 'rpms=["el8","el9"]' >> "$GITHUB_OUTPUT"
+                echo 'debs=["focal","jammy","noble"]' >> "$GITHUB_OUTPUT"
+
+        build:
+          needs: setup
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              # ✅ distro is the top-level dimension — fromJSON expands to N rows
+              distro: ${{ fromJSON(needs.setup.outputs.rpms) }}
+          steps:
+            - run: echo "Building for ${{ matrix.distro }}"
+  - language: yaml
+    label: 'Pre-combine multiple arrays into a single include list in the upstream job'
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.build-matrix.outputs.matrix }}
+          steps:
+            - id: build-matrix
+              run: |
+                # Build a combined include list from multiple arrays
+                matrix=$(python3 -c "
+                import json, sys
+                rpms = ['el8', 'el9']
+                debs = ['focal', 'jammy', 'noble']
+                include = [{'family': 'rhel', 'distro': d} for d in rpms] + \
+                          [{'family': 'debian', 'distro': d} for d in debs]
+                print(json.dumps({'include': include}))
+                ")
+                echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
+
+        build:
+          needs: setup
+          runs-on: ubuntu-latest
+          strategy:
+            # ✅ fromJSON on a single combined matrix object with include list
+            matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
+          steps:
+            - run: echo "Building ${{ matrix.family }} for ${{ matrix.distro }}"
+prevention:
+  - 'Never use `fromJSON()` as the value of a property inside a matrix object — it will not expand to multiple rows'
+  - 'Only use `fromJSON()` when the array IS the entire dimension value (e.g., `matrix.version: ${{ fromJSON(...) }}`)'
+  - 'When combining multi-dimensional dynamic matrices, pre-compute a combined `include` list in an upstream job'
+  - 'Verify matrix expansion by adding a `- run: echo ${{ toJSON(matrix) }}` debug step; "Array" in the output confirms the bug'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3794'
+    label: 'actions/runner#3794: Array outputs not understood by matrix when nested inside object (open, Apr 2025)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#using-a-matrix-strategy'
+    label: 'GitHub Docs: Using a matrix strategy'
+  - 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'

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

@@ -0,0 +1,120 @@
+id: runner-environment-246
+title: 'Container `options:` empty string from matrix causes "The template is not valid. Unexpected value''" in runner >= 2.331.0'
+category: runner-environment
+severity: error
+tags:
+  - container
+  - matrix
+  - container-options
+  - runner-regression
+  - template-validation
+  - runner-2331
+patterns:
+  - regex: 'The template is not valid.*Unexpected value'
+    flags: 'i'
+  - regex: 'Unexpected value .{0,5}\.github/workflows'
+    flags: 'i'
+error_messages:
+  - "Error: The template is not valid. .github/workflows/deploy.yml (Line: 42, Col: 15): Unexpected value ''"
+  - "Error: The template is not valid. .github/workflows/ci.yml (Line: 18, Col: 9): Unexpected value ''"
+root_cause: |
+  In runner version 2.331.0, a regression was introduced in template validation for
+  container job `options:` fields. When a workflow uses a matrix to conditionally set
+  container options — so that some matrix combinations have no container options
+  (`options: ''` or `options: ${{ matrix.container_options }}` where the value is
+  unset/empty) — the runner's template evaluator now rejects the empty string with
+  "Unexpected value ''" and marks the job as failed before it even starts.
+
+  Prior to runner 2.331.0, an empty `options:` string was silently accepted and the
+  container job ran without extra Docker options. The 2.331.0 release tightened template
+  validation for the `container.options` field, rejecting any expression that evaluates
+  to an empty string at runtime.
+
+  **Common trigger pattern:**
+  ```yaml
+  strategy:
+    matrix:
+      include:
+        - os: ubuntu
+          container_options: "--memory=2g"
+        - os: alpine
+          # No container_options key — evaluates to empty string
+  jobs:
+    build:
+      container:
+        image: myapp:latest
+        options: ${{ matrix.container_options }}  # empty for alpine row
+  ```
+
+  This pattern worked on runner 2.330.0 but fails on 2.331.0+ with "Unexpected value ''".
+  The issue is tracked in actions/runner#4204 (open, labeled bug, Jan 2026).
+fix: |
+  Add a fallback non-empty value to the options expression using the `||` operator.
+  A single space `' '` is enough to satisfy the validator while having no effect on
+  the container invocation, since Docker ignores empty/whitespace-only option strings.
+
+  Replace:
+    options: ${{ matrix.container_options }}
+
+  With:
+    options: ${{ matrix.container_options || ' ' }}
+
+  Alternatively, restructure the matrix to always provide a defined (non-empty)
+  `container_options` value, using a neutral default like `'--label=placeholder'`
+  for rows that don't need real options. This is more explicit and survives future
+  validator changes.
+fix_code:
+  - language: yaml
+    label: 'Fallback to single space so template validator accepts an empty matrix value'
+    code: |
+      strategy:
+        matrix:
+          include:
+            - name: with-limits
+              container_options: "--memory=2g --cpus=1"
+            - name: no-limits
+              # container_options intentionally absent
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: myapp:latest
+            # ✅ Use || ' ' to avoid empty-string rejection in runner >= 2.331.0
+            options: ${{ matrix.container_options || ' ' }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: 'Explicit neutral default in the matrix row avoids the ambiguity entirely'
+    code: |
+      strategy:
+        matrix:
+          include:
+            - name: with-limits
+              container_options: "--memory=2g --cpus=1"
+            - name: no-limits
+              # ✅ Always set a value — Docker ignores a dummy label at no cost
+              container_options: "--label=no-extra-opts"
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: myapp:latest
+            options: ${{ matrix.container_options }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Never let `container.options` evaluate to an empty string — always provide a neutral fallback with `|| '' ''` or a dummy label'
+  - 'Test matrix workflows with every combination, including rows that skip optional matrix keys like `container_options`'
+  - 'Pin runner version in self-hosted setups to detect regressions before rolling out to all jobs'
+  - 'Track actions/runner#4204 for a permanent fix; apply the `|| '' ''` workaround in the interim'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4204'
+    label: 'actions/runner#4204: "The template is not valid" when container.options is not set in matrix (open, regression in 2.331.0)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'GitHub Docs: Running jobs in a container — options field'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idcontaineroptions'
+    label: 'GitHub Docs: jobs.<job_id>.container.options'

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

@@ -0,0 +1,140 @@
+id: silent-failures-121
+title: '`workflow_run: types: [completed]` triggers on ALL conclusions — deploy runs even when CI failed or was cancelled'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-run
+  - conclusion
+  - silent-failure
+  - deploy-on-failure
+  - ci-cd
+  - workflow-trigger
+  - conclusion-check
+patterns:
+  - regex: 'on:\s*\n\s+workflow_run:'
+    flags: 'im'
+  - regex: 'types:\s*[\[\s]*completed[\]\s]*\n'
+    flags: 'i'
+error_messages:
+  - "# No error message — the deploy workflow runs silently even when upstream CI failed or was cancelled"
+root_cause: |
+  The `workflow_run` event with `types: [completed]` fires whenever the referenced workflow
+  finishes — regardless of its conclusion. A completed workflow can have any of these conclusions:
+  `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`,
+  or `stale`. GitHub fires `workflow_run: completed` for ALL of these states.
+
+  Developers commonly use `workflow_run` to chain a deploy or release workflow after a CI
+  workflow passes. The intuitive reading of "completed" is "finished successfully," but GitHub's
+  semantics are "finished with any outcome":
+
+  ```yaml
+  # ❌ This runs deploy even when CI failed, was cancelled, or was skipped
+  on:
+    workflow_run:
+      workflows: [CI]
+      types: [completed]
+  ```
+
+  Without an explicit `if:` conclusion check, the deploy workflow runs unconditionally after CI —
+  including when CI failed mid-run, was cancelled by a force-push, or was skipped by a path
+  filter. This silently deploys broken code (or publishes, releases, or notifies) whenever CI
+  does not succeed.
+
+  **Why this is a silent failure:**
+  - No error appears — the triggered workflow runs normally and reports "success"
+  - The CI failure and deploy completion appear as separate workflow runs — easy to miss
+  - GitHub does not add a default conclusion filter — the developer must add it manually
+  - The mistake is natural: "trigger when CI is done" sounds equivalent to "trigger when CI passes"
+
+  Sources: GitHub Docs (workflow_run event, conclusion field); SO#62750603 (159 upvotes,
+  152,034 views — top answer recommends adding conclusion check); `ahmadnassri/action-workflow-run-wait`
+  (39 stars — third-party action created specifically to work around this limitation)
+fix: |
+  Add an `if:` condition at the JOB level (not workflow level) to check
+  `github.event.workflow_run.conclusion == 'success'`. Job-level conditions are evaluated at
+  runtime after the event fires, so this reliably gates deployment on CI success.
+
+  Do NOT put the `if:` check at the workflow level — it prevents ALL jobs from running,
+  including any cleanup or notification jobs that should run regardless of conclusion.
+
+  For workflows that need to handle both success and failure (e.g., notify Slack of failures),
+  use separate jobs with different `if:` checks.
+fix_code:
+  - language: yaml
+    label: 'Add conclusion check at the job level — most common fix'
+    code: |
+      name: Deploy
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+
+      jobs:
+        deploy:
+          # ✅ Only deploy when CI succeeded
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # workflow_run always checks out default branch — use ref for PR branches
+                ref: ${{ github.event.workflow_run.head_sha }}
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Branch by conclusion — deploy on success, notify on failure'
+    code: |
+      name: Post-CI Actions
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+        notify-failure:
+          if: >-
+            github.event.workflow_run.conclusion == 'failure' ||
+            github.event.workflow_run.conclusion == 'timed_out'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify team of CI failure
+              run: |
+                echo "CI failed on branch ${{ github.event.workflow_run.head_branch }}"
+                # Send Slack/Teams notification here
+  - language: yaml
+    label: 'Anti-pattern: missing conclusion check silently deploys broken code'
+    code: |
+      # ❌ BAD: Runs even when CI failed, was cancelled, or was skipped by path filter
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]   # "completed" means ANY outcome, not just success
+
+      jobs:
+        deploy:
+          # No if: conclusion check — deploys broken code on CI failure!
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Always add `if: github.event.workflow_run.conclusion == 'success'` to deploy/release jobs triggered by workflow_run"
+  - "Remember: 'completed' means the upstream workflow finished — NOT that it succeeded; always check conclusion explicitly"
+  - "Use separate jobs with different `if: conclusion ==` checks for success vs failure vs cancelled handling"
+  - "Consider adding a linting step or actionlint check that flags workflow_run jobs without a conclusion check"
+  - "Test the failure path by intentionally failing CI and verifying the downstream workflow does NOT deploy"
+docs:
+  - 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 — conclusion field and types'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub Docs: github.event.workflow_run context properties'
+  - url: 'https://stackoverflow.com/questions/62750603/github-actions-trigger-another-action-after-one-action-is-completed'
+    label: 'SO #62750603: Trigger action after completion — top answer adds conclusion check (159 upvotes, 152k views)'
+  - url: 'https://github.com/ahmadnassri/action-workflow-run-wait'
+    label: 'ahmadnassri/action-workflow-run-wait — third-party action created to wait for successful workflow_run'

package/errors/triggers/triggers-074.yml

@@ -0,0 +1,142 @@
+id: triggers-074
+title: '`workflow_run: branches:` filter silently never triggers when upstream was started by `schedule` or `workflow_dispatch` — `head_branch` is null'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-run
+  - branches-filter
+  - head-branch
+  - schedule
+  - workflow-dispatch
+  - null
+  - silent-failure
+  - trigger-missing
+patterns:
+  - regex: 'on:\s*\n\s+workflow_run:\s*\n(.|\n)*?branches:\s*\n'
+    flags: 'im'
+  - regex: 'workflow_run.*branches.*schedule\s*$|schedule.*workflow_run.*branches'
+    flags: 'im'
+error_messages:
+  - "# No error message — the downstream workflow simply never runs when upstream was triggered by schedule or workflow_dispatch"
+root_cause: |
+  The `workflow_run` event exposes a `branches:` filter that is supposed to limit which upstream
+  workflow run conclusions trigger the downstream workflow. The filter compares against
+  `github.event.workflow_run.head_branch`.
+
+  **The problem:** When the upstream workflow is triggered by a `schedule` or `workflow_dispatch`
+  event, GitHub sets `head_branch` to `null` (not a branch name). The `branches:` filter then
+  evaluates `null` against each pattern in the list — and null never matches any branch name
+  pattern, including `[main]`, `['**']`, or any glob. The downstream workflow silently never
+  triggers, even though the upstream ran successfully on main.
+
+  **Event types that produce null head_branch:**
+  - `schedule` — cron-triggered workflows have no associated branch context
+  - `workflow_dispatch` — manually dispatched workflows MAY have null head_branch in some cases
+
+  **Pull request triggers correctly populate head_branch** (the PR head branch name), and
+  `push` triggers also correctly populate it (the pushed branch name). The null behavior is
+  specific to schedule and dispatch events on the upstream.
+
+  **Why this is a silent failure:**
+  - No error is raised — the downstream workflow simply does not appear in the Actions UI for that run
+  - The upstream workflow runs and completes successfully
+  - The `branches:` filter looks correct — `[main]` is the right branch name
+  - The issue only manifests for schedule/dispatch-triggered upstream runs; if CI also triggers
+    on push to main, push-triggered runs DO reach the downstream workflow
+
+  **Example scenario:** A deploy workflow runs after CI. CI has `on: [push, schedule]`.
+  The `branches: [main]` filter in the deploy's workflow_run block works for push events but
+  silently skips all scheduled CI runs.
+
+  Sources: GitHub Docs (workflow_run, head_branch null for schedule); community/discussions
+  related to workflow_run not triggering after schedule; documented in
+  `workflow-run-head-branch-null-schedule-dispatch-concurrency.yml` (concurrency variant)
+fix: |
+  Remove the `branches:` filter from the `workflow_run` trigger entirely and instead use a
+  job-level `if:` condition to check the branch after the event fires. The `if:` condition
+  evaluates at runtime and can handle null gracefully.
+
+  For schedule-triggered upstreams, use `github.event.workflow_run.head_branch == 'main' ||
+  github.event.workflow_run.head_branch == null` (null means it ran from the default branch).
+
+  Alternatively, filter by the workflow run's `head_sha` and check against known branch SHAs.
+fix_code:
+  - language: yaml
+    label: 'Remove branches filter and add job-level if condition — handles schedule and dispatch'
+    code: |
+      name: Deploy After CI
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          # ❌ Do NOT use branches: here if CI runs on schedule or workflow_dispatch
+          # branches: [main]   # This silently skips all schedule-triggered CI runs
+
+      jobs:
+        deploy:
+          # ✅ Use job-level if: instead of trigger-level branches:
+          # null head_branch means schedule/dispatch from default branch — include it
+          if: >-
+            github.event.workflow_run.conclusion == 'success' &&
+            (github.event.workflow_run.head_branch == 'main' ||
+             github.event.workflow_run.head_branch == null)
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'When upstream is push-only: branches filter works fine (head_branch is always set)'
+    code: |
+      name: Deploy After CI (push-only upstream)
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          # ✅ branches: filter works correctly ONLY when upstream runs on push or pull_request
+          # Because push and pull_request events always set head_branch
+          branches: [main]
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+
+      # ⚠️ If CI also has on: schedule — add null check above or remove branches: filter
+  - language: yaml
+    label: 'Anti-pattern: branches filter with schedule-triggered upstream — downstream never fires'
+    code: |
+      # ❌ BAD: Upstream CI has on: [push, schedule]
+      # But deploy's branches filter silently skips all scheduled CI runs
+
+      name: Deploy After CI
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          branches: [main]   # null (from schedule) never matches 'main' — deploy skipped!
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh   # Never runs after scheduled CI
+prevention:
+  - "Avoid `branches:` filter in workflow_run if the upstream workflow can be triggered by `schedule` or `workflow_dispatch`"
+  - "Use job-level `if:` conditions with explicit null handling instead of trigger-level branch filters"
+  - "Check the upstream workflow's triggers — if it includes `schedule` or `workflow_dispatch`, `head_branch` will be null for those runs"
+  - "Test by triggering the upstream workflow manually and verifying the downstream workflow appears in the Actions UI"
+  - "When null head_branch is acceptable (schedule from default branch), use `head_branch == 'main' || head_branch == null`"
+docs:
+  - 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 — branches filter and head_branch field'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub Docs: github.event.workflow_run — head_branch property (null for schedule/dispatch)'
+  - url: 'https://github.com/orgs/community/discussions/26238'
+    label: 'GitHub Community: workflow_run not triggering — head_branch null discussion'

package/package.json

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