@htekdev/actions-debugger 1.0.61 → 1.0.63

package/errors/caching-artifacts/cache-key-github-sha-no-restore.yml

@@ -0,0 +1,72 @@
+id: caching-artifacts-042
+title: "Cache key containing github.sha always misses on restore — cache is saved but never reused"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cache-key
+  - github-sha
+  - cache-miss
+  - restore-keys
+  - performance
+patterns:
+  - regex: 'Cache not found for input keys: .*\b[0-9a-f]{40}\b'
+    flags: i
+  - regex: 'Warning: Cache not found for.*sha.*\.'
+    flags: i
+  - regex: 'Cache restored from key: .*\b[0-9a-f]{40}\b'
+    flags: i
+error_messages:
+  - "Cache not found for input keys: Linux-node-a3f2b1c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
+  - "Warning: Cache not found for key: ubuntu-latest-npm-abc1234def5678901234567890abcdef12345678"
+root_cause: |
+  When a cache key includes ${{ github.sha }}, every commit produces a unique key. The cache is
+  saved successfully at the end of the workflow, but on the very next run the sha is different,
+  so the restore step finds no matching cache entry and declares a miss. This pattern ensures
+  the cache is written once and thrown away — it provides no performance benefit.
+
+  This mistake is common because github.sha is a readily available context value and its use
+  in cache keys looks reasonable at first glance. The cache action's restore-keys fallback
+  mechanism would normally rescue a miss, but developers often omit restore-keys when using
+  sha-based keys, expecting the primary key to match.
+fix: |
+  Replace github.sha with a hash of the files that determine cache validity, such as
+  hashFiles('**/package-lock.json') for npm or hashFiles('**/go.sum') for Go. Use github.sha
+  only as a restore-keys fallback prefix if you want a per-commit cache layer on top of a
+  stable base cache. The cache key should be stable across commits unless the relevant
+  dependency manifest changes.
+fix_code:
+  - language: yaml
+    label: "Correct cache key using hashFiles instead of github.sha"
+    code: |
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "Per-commit layer on top of a stable base cache (advanced)"
+    code: |
+      # Stable key hits on re-runs; sha layer saves per-commit installs
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            ${{ runner.os }}-node-
+prevention:
+  - "Never use github.sha as a primary cache key unless you explicitly want a per-commit cache that never restores"
+  - "Use hashFiles() over the relevant lock file or manifest as the stable portion of the cache key"
+  - "Always add restore-keys with progressively broader prefixes to benefit from partial cache hits"
+  - "Check the cache hit rate in the Actions UI — 0% hit rate on restore is a sign the key is too unique"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#using-the-cache-action
+    label: "GitHub Docs: Using the cache action"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key
+    label: "GitHub Docs: Matching a cache key"
+  - url: https://stackoverflow.com/questions/59435153/github-actions-cache-miss-every-run
+    label: "Stack Overflow: GitHub Actions cache miss every run"

package/errors/permissions-auth/github-token-fork-pr-read-only.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-045
+title: "GITHUB_TOKEN has read-only access in pull_request workflows from forks — write operations return 403"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - fork
+  - pull-request
+  - read-only
+  - permissions
+  - resource-not-accessible
+  - write-access
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: i
+  - regex: 'HttpError: Resource not accessible by integration'
+    flags: i
+  - regex: 'Error: HttpError: Not Found.*token.*forked'
+    flags: i
+  - regex: 'refused.*write.*403.*pull_request.*fork'
+    flags: i
+error_messages:
+  - "Error: Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+  - "Error: HttpError: Resource not accessible by integration"
+root_cause: |
+  When a pull_request workflow is triggered by a PR from a forked repository, GitHub
+  automatically restricts the GITHUB_TOKEN to read-only permissions. This security measure
+  prevents malicious PRs from using the token to modify the base repository — the token
+  cannot create issues, post comments, create releases, trigger deployments, or write to
+  the repository. Workflows see a token that behaves as if all write permissions were denied.
+
+  This restriction applies even if the workflow YAML has explicit permissions: write entries.
+  The fork security boundary takes precedence. The workflow still runs (unlike pull_request_target
+  which runs with base repo permissions), but the token scope is silently reduced.
+
+  Common victims include: posting PR comments with github-script, uploading artifacts to
+  releases, creating check runs, and updating commit statuses.
+fix: |
+  Use the pull_request_target event if the workflow must write to the base repo. Be aware
+  that pull_request_target checks out the base branch by default (not the PR head) and carries
+  security implications — never checkout and execute untrusted PR code with write-permission
+  tokens (see pwn request attacks). For safe comment posting, split into two workflows:
+  a read-only pull_request workflow that uploads results as an artifact, and a
+  pull_request_target or workflow_run workflow with write access that downloads the artifact
+  and posts the comment.
+fix_code:
+  - language: yaml
+    label: "Split pattern — upload results in pull_request, post comment in workflow_run"
+    code: |
+      # Workflow 1: pr-test.yml — runs on pull_request (fork-safe, read-only token)
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests and save results
+              run: npm test > test-results.txt 2>&1 || true
+            - name: Upload PR number for downstream workflow
+              uses: actions/upload-artifact@v4
+              with:
+                name: pr-results
+                path: |
+                  test-results.txt
+  - language: yaml
+    label: "Workflow 2 — post comment using workflow_run (has write token)"
+    code: |
+      # Workflow 2: pr-comment.yml — runs after pr-test.yml completes (has write token)
+      on:
+        workflow_run:
+          workflows: ["PR Tests"]
+          types: [completed]
+
+      permissions:
+        pull-requests: write
+
+      jobs:
+        comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download test results artifact
+              uses: actions/download-artifact@v4
+              with:
+                name: pr-results
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Post PR comment
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const fs = require('fs');
+                  const results = fs.readFileSync('test-results.txt', 'utf8');
+                  await github.rest.issues.createComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: context.payload.workflow_run.pull_requests[0].number,
+                    body: '## Test Results\n```\n' + results + '\n```'
+                  });
+prevention:
+  - "Know that GITHUB_TOKEN is read-only for PR workflows from forks — this is a security feature, not a misconfiguration"
+  - "Never use pull_request_target to run PR head code with write-permission tokens — this creates a pwn request vulnerability"
+  - "Use the upload-artifact + workflow_run split pattern for safe cross-fork write operations"
+  - "Test workflows with a fork PR specifically if they perform write operations — the token scope difference won't appear in same-repo PRs"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+    label: "GitHub Docs: pull_request event — fork permission restrictions"
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+    label: "GitHub Docs: GITHUB_TOKEN permissions"
+  - url: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+    label: "GitHub Security Lab: Preventing pwn requests (pull_request_target risks)"
+  - url: https://stackoverflow.com/questions/70435286/resource-not-accessible-by-integration-on-github-pull-request-event
+    label: "Stack Overflow: Resource not accessible by integration on pull_request"

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

@@ -0,0 +1,82 @@
+id: permissions-auth-044
+title: "OIDC token sub claim format changes inside reusable workflow jobs, breaking cloud provider trust policies"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - reusable-workflow
+  - aws
+  - gcp
+  - trust-policy
+  - sub-claim
+  - job-workflow-ref
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: i
+  - regex: 'failed to generate Google Cloud federated token'
+    flags: i
+  - regex: 'Credentials could not be loaded.*Could not load credentials from any providers'
+    flags: i
+error_messages:
+  - "An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation: Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "Error: google-github-actions/auth failed to generate Google Cloud federated token for..."
+  - "Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+root_cause: |
+  When a job runs inside a reusable workflow (called via uses:), GitHub changes the format of
+  the OIDC token sub claim to include the calling workflow's path. For a direct job the sub is:
+    repo:ORG/REPO:ref:refs/heads/main
+  For a job inside a reusable workflow the sub becomes:
+    repo:ORG/REPO:job_workflow_ref:ORG/REPO/.github/workflows/reusable.yml@refs/heads/main
+  AWS IAM OIDC trust policies and GCP Workload Identity Federation attribute conditions that
+  were configured to match the simpler ref-based sub format now reject the OIDC token with an
+  AccessDenied error. The error message gives no indication that the sub claim format changed —
+  it looks identical to any other OIDC trust policy mismatch.
+fix: |
+  Update the cloud provider's OIDC trust policy to match the new sub claim format used by
+  reusable workflow jobs. For AWS, update the IAM trust policy StringLike condition to match
+  job_workflow_ref instead of ref. For GCP, update the attribute condition in the Workload
+  Identity Pool provider. Alternatively, use GitHub's OIDC subject claim customization feature
+  (repo Settings → Actions → General → OIDC subject claims) to define a consistent sub claim
+  template that works for both caller and reusable workflow jobs.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow with id-token permission declared (required)"
+    code: |
+      # In the reusable workflow file (.github/workflows/reusable.yml):
+      on:
+        workflow_call:
+
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/my-role
+                aws-region: us-east-1
+  - language: yaml
+    label: "AWS IAM trust policy StringLike condition for reusable workflow sub claim"
+    code: |
+      # Update AWS IAM role trust policy Condition block to match reusable workflow sub format.
+      # Old (direct job):   "repo:ORG/REPO:ref:refs/heads/main"
+      # New (reusable job): "repo:ORG/REPO:job_workflow_ref:ORG/REPO/.github/workflows/reusable.yml@refs/heads/main"
+      #
+      # Use a wildcard to allow both patterns:
+      # "token.actions.githubusercontent.com:sub": "StringLike": ["repo:ORG/REPO:*"]
+prevention:
+  - "When refactoring direct jobs into reusable workflows, update cloud OIDC trust policies before deploying"
+  - "Use GitHub subject claim customization to define a consistent sub format that works across direct and reusable jobs"
+  - "Document the expected OIDC sub claim format in the reusable workflow README alongside cloud policy requirements"
+  - "Test OIDC authentication in a staging cloud environment when moving jobs into reusable workflows"
+docs:
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
+    label: "GitHub Docs: Using OIDC with reusable workflows"
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository
+    label: "GitHub Docs: Customizing OIDC subject claims"
+  - url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
+    label: "AWS Docs: Creating IAM OIDC identity providers"

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

@@ -0,0 +1,61 @@
+id: runner-environment-123
+title: "actions/checkout@v6 breaks Docker container actions that use git authentication"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - v6
+  - docker
+  - container-action
+  - git-auth
+  - breaking-change
+patterns:
+  - regex: 'fatal: could not read Username for.*No such device or address'
+    flags: i
+  - regex: 'fatal: Authentication failed for.*github\.com'
+    flags: i
+  - regex: 'fatal: credential helper.*is not executable'
+    flags: i
+error_messages:
+  - "fatal: could not read Username for 'https://github.com/': No such device or address"
+  - "fatal: Authentication failed for 'https://github.com/org/repo.git/'"
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+root_cause: |
+  actions/checkout@v6 changed credential storage: credentials are now written to the runner's
+  native credential manager rather than the global gitconfig file. Docker container actions run
+  in isolated containers without access to the runner host's credential store, so any git
+  operations inside a Docker-based action or container: job that require authentication fail.
+  This is a breaking change from v5, where credentials were written to gitconfig and could be
+  inherited by Docker containers. The v6 runner PR #4011 introduced this mechanism and Docker
+  container action support is gated behind a feature flag not yet enabled for all runners.
+fix: |
+  Pin to actions/checkout@v5 for workflows that rely on Docker container actions making
+  authenticated git calls. Monitor the actions/checkout issue tracker for v6 Docker container
+  action support. Alternatively, pass the GITHUB_TOKEN as an environment variable to the Docker
+  action and configure credentials inside the container's own entrypoint script.
+fix_code:
+  - language: yaml
+    label: "Pin to actions/checkout@v5 for Docker container action compatibility"
+    code: |
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Pass token as env var to Docker action for container-side credential setup"
+    code: |
+      - name: Run Docker-based action with explicit token
+        uses: org/my-docker-action@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Pin actions/checkout to a tested major version and review release notes before upgrading to a new major"
+  - "Audit workflows for Docker container actions that perform authenticated repository operations before upgrading checkout"
+  - "Test Docker-based custom actions in CI against the new checkout version before rolling out"
+docs:
+  - url: https://github.com/actions/checkout/issues/2313
+    label: "actions/checkout#2313: v6 breaks Docker actions that use git authentication"
+  - url: https://github.com/orgs/community/discussions/179107
+    label: "GitHub Community: actions/checkout v6 changes discussion"
+  - url: https://github.com/actions/runner/pull/4011
+    label: "actions/runner PR#4011: credential manager changes introduced in v6"

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

@@ -0,0 +1,68 @@
+id: runner-environment-124
+title: "actions/setup-go@v6 GOTOOLCHAIN auto mode downloads unexpected Go version from go.mod toolchain directive"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-go
+  - v6
+  - gotoolchain
+  - go-version
+  - toolchain-directive
+  - breaking-change
+patterns:
+  - regex: 'go: downloading go\d+\.\d+\.\d+ \('
+    flags: i
+  - regex: 'toolchain go\d+\.\d+\.\d+ cannot be used because it would require a later version'
+    flags: i
+  - regex: 'go: toolchain go\d+\.\d+\.\d+ not available on GOPROXY'
+    flags: i
+error_messages:
+  - "go: downloading go1.23.4 (linux/amd64)"
+  - "toolchain go1.23.4 cannot be used because it would require a later version"
+  - "go: toolchain go1.23.4 not available on GOPROXY"
+root_cause: |
+  actions/setup-go@v6 (released September 2025) changed toolchain handling to honor Go 1.21+
+  GOTOOLCHAIN semantics. When a go.mod file contains a 'toolchain goX.Y.Z' directive and
+  GOTOOLCHAIN is set to 'auto' (the default for Go 1.21+), Go will automatically download the
+  toolchain version specified in go.mod rather than using the version installed by setup-go.
+  The workflow runs with a different Go version than the one specified in the go-version: input,
+  causing unexpected behavior, build failures, or unintended Go version usage. In v5, setup-go
+  implicitly set GOTOOLCHAIN=local, preventing automatic toolchain downloads. v6 removed this
+  implicit override, meaning go.mod toolchain directives now take effect in CI.
+fix: |
+  Set GOTOOLCHAIN=local in the step environment to force Go to use exactly the version installed
+  by setup-go, ignoring the toolchain directive in go.mod. Alternatively, align the go-version:
+  input with the toolchain directive in go.mod, or use go-version-file: go.mod to let setup-go
+  read the version directly from the module file.
+fix_code:
+  - language: yaml
+    label: "Set GOTOOLCHAIN=local to prevent auto-download — use exactly the installed version"
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.22'
+
+      - name: Build
+        run: go build ./...
+        env:
+          GOTOOLCHAIN: local   # disables auto-download; uses only the version from setup-go
+  - language: yaml
+    label: "Or read go-version directly from go.mod to stay aligned with the toolchain directive"
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod   # reads 'go X.Y' line from go.mod; stays in sync automatically
+prevention:
+  - "After upgrading to setup-go@v6, verify the actual Go version used in builds matches the go-version: input"
+  - "Add GOTOOLCHAIN=local to workflow env or per-step env to opt out of automatic toolchain download behavior"
+  - "Keep the go.mod toolchain directive in sync with the go-version: value specified in setup-go"
+  - "Use go-version-file: go.mod instead of an explicit go-version: value to stay automatically aligned"
+docs:
+  - url: https://github.com/actions/setup-go/releases/tag/v6.0.0
+    label: "actions/setup-go v6.0.0 release notes — toolchain handling breaking change"
+  - url: https://github.com/actions/setup-go/pull/460
+    label: "actions/setup-go PR#460: Improve toolchain handling"
+  - url: https://go.dev/doc/toolchain
+    label: "Go documentation: Toolchains — GOTOOLCHAIN environment variable"

package/errors/silent-failures/cache-hit-output-empty-string-not-false.yml

@@ -0,0 +1,87 @@
+id: silent-failures-063
+title: "actions/cache cache-hit output is empty string on miss, not 'false' — equality checks silently never match"
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions-cache
+  - cache-hit
+  - output
+  - empty-string
+  - if-condition
+  - false-comparison
+patterns:
+  - regex: 'steps\.\w+\.outputs\.cache-hit\s*==\s*[''"]false[''"]'
+    flags: i
+  - regex: "cache-hit.*==.*'false'"
+    flags: i
+error_messages:
+  - "cache-hit output comparison to 'false' always evaluates to false — use != 'true' instead"
+root_cause: |
+  The actions/cache action sets the cache-hit output to the string 'true' when a cache is
+  restored from an exact key match, and to an empty string '' when the cache is not found
+  (including when restored from a restore-keys fallback, which returns '' for cache-hit in v3
+  and 'false' only in some v4 configurations). This means that
+  `if: steps.cache.outputs.cache-hit == 'false'` evaluates to false on a cache miss because
+  '' != 'false', so the step or job it guards is silently skipped.
+
+  This is one of the most upvoted GitHub Actions questions on Stack Overflow. Developers
+  naturally expect a boolean-like output to be 'true' or 'false', but the cache action uses
+  'true' vs '' (empty) semantics. The step appears to run successfully; nothing in the logs
+  indicates the if condition did not match as expected.
+fix: |
+  Check for cache miss using != 'true' instead of == 'false'. An empty string and 'false'
+  both evaluate to not-equal-to-'true', so this pattern correctly handles all cache miss
+  cases across cache action versions. Alternatively, use the boolean expression
+  `steps.cache.outputs.cache-hit != 'true'` or omit the check and rely on the cache action's
+  lookup-only: true parameter combined with a separate save step.
+fix_code:
+  - language: yaml
+    label: "Use != 'true' to reliably detect cache miss (works across all cache action versions)"
+    code: |
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      # WRONG — silently never runs on cache miss:
+      # - name: Install deps
+      #   if: steps.cache-deps.outputs.cache-hit == 'false'
+
+      # CORRECT — matches both '' and 'false':
+      - name: Install dependencies
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Lookup-only + explicit save pattern (cache@v4) to avoid output ambiguity"
+    code: |
+      - name: Restore cache (lookup only, no auto-save)
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Install dependencies
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Save cache
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - "Always use != 'true' to check for cache miss — never use == 'false' on cache action outputs"
+  - "Review the cache action version changelog: v3 uses '' on miss, v4 behavior depends on exact/partial hit"
+  - "Add a debug step that echoes cache-hit output to make cache behavior visible in logs during development"
+  - "Consult the cache action README for the exact semantics of cache-hit, cache-primary-key, and cache-matched-key"
+docs:
+  - url: https://github.com/actions/cache#outputs
+    label: "actions/cache README: Outputs"
+  - url: https://stackoverflow.com/questions/62754195/github-actions-cache-hit-is-true-but-id-expect-false
+    label: "Stack Overflow: cache-hit is empty string, not 'false'"
+  - url: https://github.com/actions/cache/issues/1699
+    label: "actions/cache#1699: cache-hit output '' vs 'false' confusion"

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

@@ -0,0 +1,66 @@
+id: silent-failures-062
+title: "actions/cache save failure emits Warning annotation but does not fail the workflow step"
+category: silent-failures
+severity: silent-failure
+tags:
+  - cache
+  - cache-save
+  - warning
+  - non-fatal
+  - false-success
+  - cache-service
+patterns:
+  - regex: 'Warning: Failed to save:.*Failed to CreateCacheEntry.*non-retryable'
+    flags: i
+  - regex: 'Warning: Failed to restore:.*Failed to GetCacheEntryDownloadURL.*non-retryable'
+    flags: i
+error_messages:
+  - "Warning: Failed to save: Failed to CreateCacheEntry: Received non-retryable error: Failed request: (404) Not Found: invalid request"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Received non-retryable error: Failed request: (404) Not Found: invalid request"
+root_cause: |
+  The actions/cache and actions/cache/save actions treat upload failures as non-fatal warnings
+  rather than step errors. When the GitHub cache backend returns an error (4xx/5xx), is
+  unavailable, or rejects the request, the action emits a yellow Warning annotation in the
+  workflow log but exits with code 0. The workflow step is marked green (success). Downstream
+  runs then see genuine "Cache not found" misses since nothing was persisted. Developers assume
+  the cache was saved based on the green checkmark, spending hours debugging unreliable cache
+  restore before finding the Warning annotation buried in the save step output. This behavior is
+  intentional — cache is treated as an optimization, not a requirement — but it means failures
+  are invisible unless annotations are actively checked.
+fix: |
+  Check step-level annotations (the yellow warning triangle icon) on cache save steps, not just
+  the green/red status indicator. Use fail-on-cache-miss: true on restore steps when cache
+  availability is critical to your build speed so that a missing cache surfaces as a hard
+  failure. For save failures there is no built-in fail flag — add a downstream validation step
+  if guaranteed cache persistence is required. Always use supported cache action versions
+  (actions/cache@v3 or @v4) to ensure compatibility with the current cache backend service.
+fix_code:
+  - language: yaml
+    label: "Use fail-on-cache-miss on restore to surface missing cache as an error"
+    code: |
+      - name: Restore build cache
+        id: restore-cache
+        uses: actions/cache/restore@v4
+        with:
+          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
+          path: ~/.npm
+          fail-on-cache-miss: true   # step fails with error if nothing was previously saved
+
+      - name: Save build cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
+          path: ~/.npm
+prevention:
+  - "Always check workflow annotations (yellow warning triangle) in addition to the step pass/fail status"
+  - "Use actions/cache@v4 or @v3 — deprecated pinned SHAs may fail silently after the cache backend migration"
+  - "Use fail-on-cache-miss: true on restore steps to make cache misses visible as hard failures"
+  - "Monitor the actions/cache issue tracker when cache restore reliability degrades — backend incidents are reported quickly"
+docs:
+  - url: https://github.com/actions/cache/issues/1541
+    label: "actions/cache#1541: Bug: Failed to CreateCacheEntry (29 reactions, Feb 2025)"
+  - url: https://github.com/actions/cache/discussions/1510
+    label: "actions/cache Discussion#1510: Deprecation Notice — upgrade to latest before Feb 2025"
+  - 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 — fail-on-cache-miss option"

package/errors/triggers/push-paths-filter-no-effect-workflow-dispatch.yml

@@ -0,0 +1,81 @@
+id: triggers-045
+title: "on.push.paths filter has no effect on workflow_dispatch — manual trigger always runs regardless of changed files"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - push
+  - paths-filter
+  - triggers
+  - manual-trigger
+  - always-runs
+patterns:
+  - regex: 'workflow_dispatch'
+    flags: i
+error_messages:
+  - "Workflow ran unexpectedly when triggered via workflow_dispatch despite paths filter"
+root_cause: |
+  GitHub Actions evaluates on.push.paths (and on.push.paths-ignore) filters only for push
+  events. The filter is tied to the event type it is defined under. When workflow_dispatch is
+  added as a separate trigger, it has no paths context — there is no commit diff associated
+  with a manual dispatch. GitHub therefore runs the workflow unconditionally when dispatched.
+
+  This surprises developers who add workflow_dispatch: to an existing push-triggered workflow
+  for convenience and expect the paths filter to still gate the run. The workflow_dispatch
+  event has no paths or branches key at all; any such keys would be silently ignored if added.
+
+  A related confusion: paths filters on pull_request or push do not protect against
+  workflow_dispatch, so adding a workflow_dispatch trigger effectively creates an unfiltered
+  entry point into the workflow.
+fix: |
+  Accept that workflow_dispatch runs unconditionally — this is intentional GitHub behavior.
+  If you want to restrict what the dispatched workflow does based on inputs, use
+  workflow_dispatch inputs to pass a flag and gate steps with if: conditions. If the goal is
+  to limit accidental runs, remove workflow_dispatch from workflows where paths-gating is
+  critical, or add a required input that must be confirmed before proceeding.
+fix_code:
+  - language: yaml
+    label: "Separate push-only workflow (with paths filter) from a dispatch-friendly workflow"
+    code: |
+      # Option 1: keep push and dispatch as separate workflow files
+      # push-filtered.yml — only triggered on relevant path changes
+      on:
+        push:
+          paths:
+            - 'src/**'
+
+      # dispatch-build.yml — no paths filter needed; always intentional
+      on:
+        workflow_dispatch:
+  - language: yaml
+    label: "Use a workflow_dispatch input to require confirmation before running"
+    code: |
+      on:
+        push:
+          paths:
+            - 'src/**'
+        workflow_dispatch:
+          inputs:
+            confirm:
+              description: 'Type YES to run regardless of changed files'
+              required: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Proceed only if push triggered by path change OR dispatch confirmed
+              if: github.event_name == 'push' || inputs.confirm == 'YES'
+              run: echo "Running build"
+prevention:
+  - "Understand that paths/branches filters are per-event-type — workflow_dispatch has no file diff context"
+  - "Document in the workflow file that workflow_dispatch runs unconditionally to avoid future confusion"
+  - "Use workflow_dispatch inputs to gate critical steps when a manual trigger is added to a path-filtered workflow"
+  - "Review which workflows have both push.paths filters and workflow_dispatch before adding the dispatch trigger"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
+    label: "GitHub Docs: workflow_dispatch event"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-branches-or-tags-for-push-events
+    label: "GitHub Docs: Using filters to target specific paths"
+  - url: https://stackoverflow.com/questions/65900201/workflow-dispatch-ignores-paths-filter
+    label: "Stack Overflow: workflow_dispatch ignores paths filter"

package/package.json

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