@htekdev/actions-debugger 1.0.118 → 1.0.120

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

@@ -0,0 +1,124 @@
+id: known-unsolved-068
+title: "Step outcome cannot distinguish timeout from failure — both report as 'failure' in steps context"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - outcome
+  - conclusion
+  - continue-on-error
+  - steps-context
+  - retry
+  - known-limitation
+  - no-fix
+patterns:
+  - regex: 'steps\.\w+\.outcome\s*==\s*.failure.'
+    flags: 'i'
+  - regex: 'timeout-minutes.*continue-on-error|continue-on-error.*timeout-minutes'
+    flags: 'im'
+  - regex: 'The process.*timed out after \d+ minutes'
+    flags: 'i'
+error_messages:
+  - "Error: The process '/usr/bin/bash' failed with exit code 1"
+  - 'Error: Process completed with exit code 1'
+root_cause: |
+  GitHub Actions exposes two result fields for completed steps in the steps context:
+
+  - steps.<id>.outcome: the raw result before continue-on-error is applied.
+    Possible values: success, failure, cancelled, skipped.
+  - steps.<id>.conclusion: the final result after continue-on-error is applied.
+    When continue-on-error: true is set on a failed step, conclusion becomes 'success'
+    even if outcome is 'failure'.
+
+  Neither field distinguishes between a step that failed because the process exited with a
+  non-zero code and a step that failed because it hit its timeout-minutes limit. Both
+  scenarios set outcome to 'failure'. There is no 'timed_out' value, no
+  steps.<id>.timed_out boolean, and no built-in expression function to query the reason
+  for failure.
+
+  This means workflows cannot natively:
+  - Retry only on timeout while failing fast on real errors
+  - Alert with different severity for timeouts vs application failures
+  - Auto-escalate timeout-minutes only when a timeout (not a logic error) occurred
+
+  The limitation has been a known open request in the GitHub Actions community since at
+  least 2022 with no current implementation timeline from GitHub.
+fix: |
+  No native fix exists within GitHub Actions expressions. Two manual workarounds are
+  available in bash-based steps:
+
+  1. Record start time and compute elapsed duration at the next step to infer timeout:
+     Compare elapsed seconds against the timeout-minutes threshold. A step that used
+     approximately 100% of its time budget likely timed out.
+
+  2. Write a sentinel file just before the critical work; check for its absence afterward.
+     A timed-out step never reaches the sentinel-write line after the long-running command,
+     while a normally-failing step (which exits immediately on error) may or may not.
+
+  Neither workaround is exact — both have race conditions and edge cases. The most
+  reliable approach is to implement timeout detection inside the script itself using
+  shell signals or test-framework timeout flags.
+fix_code:
+  - language: yaml
+    label: 'Workaround 1: Infer timeout via elapsed time'
+    code: |
+      - name: Start timer
+        id: timer
+        run: echo "start=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Run slow tests
+        id: tests
+        timeout-minutes: 10
+        continue-on-error: true
+        run: npm test
+
+      - name: Classify failure type
+        if: steps.tests.outcome == 'failure'
+        env:
+          START: ${{ steps.timer.outputs.start }}
+        run: |
+          elapsed=$(( $(date +%s) - START ))
+          timeout_secs=600   # 10 minutes in seconds
+          threshold=$(( timeout_secs - 30 ))  # within 30s of limit → likely timeout
+          if [ "$elapsed" -ge "$threshold" ]; then
+            echo "::warning::Step likely timed out (elapsed ${elapsed}s, limit ${timeout_secs}s)"
+            # Handle timeout-specific logic here (e.g., don't fail, just warn)
+          else
+            echo "::error::Step failed (exit code, not timeout — elapsed ${elapsed}s)"
+            exit 1
+          fi
+  - language: yaml
+    label: 'Workaround 2: Sentinel file to detect timeout vs normal failure'
+    code: |
+      - name: Run tests with sentinel
+        id: tests
+        timeout-minutes: 10
+        continue-on-error: true
+        run: |
+          # The long-running command:
+          npm test
+          # Only reached on clean exit (not timeout, not error):
+          touch /tmp/test-completed
+
+      - name: Check failure reason
+        if: steps.tests.outcome == 'failure'
+        run: |
+          if [ ! -f /tmp/test-completed ]; then
+            echo "Step timed out or failed before completing"
+            # Inspect logs for timeout keyword:
+            # If the runner log shows "The process timed out after N minutes" → it was timeout
+          else
+            echo "Step completed but exited non-zero — application failure"
+            exit 1
+          fi
+prevention:
+  - 'Log test durations inside the script itself; test framework flags like --testTimeout (Jest) or --timeout (Mocha) provide per-test granularity inside logs.'
+  - 'Use separate jobs for steps with different timeout characteristics — a dedicated integration-test job with a high timeout-minutes and a unit-test job with a low one makes failures easier to categorize.'
+  - 'If the step runs a single long command, wrap it in a shell timeout with a slightly shorter duration than timeout-minutes; the shell timeout exit code (124) is detectable inside the same step.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context'
+    label: 'GitHub Docs: steps context — outcome and conclusion fields'
+  - url: 'https://stackoverflow.com/questions/78233438/github-action-cannot-get-timeout-status-from-previous-step'
+    label: 'SO: Cannot get timeout status from previous step (Mar 2024)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Status check functions (failure, success, cancelled, always)'

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

@@ -0,0 +1,127 @@
+id: known-unsolved-069
+title: "Matrix Strategy Hard Limit: 256 Jobs Per Workflow Run"
+category: known-unsolved
+severity: error
+tags:
+  - matrix
+  - strategy
+  - job-limit
+  - dynamic-matrix
+  - fromjson
+  - scalability
+patterns:
+  - regex: 'matrix.*generates.*too many|too many.*entries.*matrix'
+    flags: 'i'
+  - regex: 'limited to 256|exceeding.*allowed maximum.*256|256.*jobs.*per.*workflow'
+    flags: 'i'
+error_messages:
+  - "Matrix generates too many entries. Limited to 256."
+root_cause: |
+  GitHub Actions enforces a hard limit of 256 jobs per workflow run across
+  all matrix dimensions. This is calculated as the total Cartesian product of
+  all matrix axes after applying include/exclude entries.
+
+  Common triggers:
+  - Dynamic matrices from fromJSON output that grow over time as new targets
+    are added to a test matrix config file
+  - Multi-dimensional matrices (os x language x version) where the product
+    of all axis sizes exceeds 256
+  - Adding include: entries on top of an already-large base matrix, each
+    include: adds one additional job that counts against the 256 limit
+  - Monorepo CI matrices that test all services x all supported runtimes
+
+  The error fires immediately when the workflow is queued and prevents any
+  jobs from running. GitHub reports the total generated count in the error
+  message: "Matrix generates N entries. Limited to 256."
+
+  This limit applies equally to GitHub-hosted and self-hosted runners and
+  cannot be increased by contacting support.
+fix: |
+  The 256-job-per-run limit is hard and cannot be increased. Options:
+
+  1. Split across multiple workflow files, each handling a subset of targets.
+     Trigger them from a parent coordinator workflow or via separate triggers.
+
+  2. Reduce matrix dimensions: test only meaningful combinations using
+     explicit include: lists rather than full Cartesian products. Not every
+     OS x language x version triplet needs to be tested.
+
+  3. Chunk using workflow_dispatch fan-out: a generator job creates N chunks
+     of at most 256 items and dispatches sub-workflow runs per chunk via
+     repository_dispatch or workflow_dispatch API calls.
+
+  4. Use a single job with a shell loop for some dimensions: instead of
+     separate matrix jobs per version, loop over versions inside one job step.
+     Sacrifices parallelism but avoids the limit entirely.
+fix_code:
+  - language: yaml
+    label: "Broken — Cartesian product silently grows past 256 as versions are added"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-22.04, ubuntu-24.04, windows-2022, macos-14, macos-15]
+          node: [18, 20, 22, 23]
+          python: ['3.9', '3.10', '3.11', '3.12', '3.13']
+          # 5 x 4 x 5 = 100 jobs today — fine, but adding node 24 pushes to 125,
+          # adding python 3.14 pushes to 150, and so on until 256 is silently hit
+
+  - language: yaml
+    label: "Fixed — explicit include list tests only meaningful combinations"
+    code: |
+      strategy:
+        matrix:
+          include:
+            # Test LTS node on primary OS with latest stable Python
+            - os: ubuntu-24.04
+              node: 20
+              python: '3.12'
+            - os: ubuntu-24.04
+              node: 22
+              python: '3.12'
+            # Windows only gets the most recent LTS
+            - os: windows-2022
+              node: 20
+              python: '3.11'
+            # macOS gets one combination
+            - os: macos-15
+              node: 20
+              python: '3.12'
+          # Total: 4 jobs instead of 100+ from full Cartesian product
+
+  - language: yaml
+    label: "Defensive — validate dynamic matrix size before passing to strategy"
+    code: |
+      jobs:
+        generate-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.gen.outputs.matrix }}
+          steps:
+            - id: gen
+              run: |
+                MATRIX=$(cat test-matrix.json)
+                COUNT=$(echo "$MATRIX" | jq '.include | length')
+                if [ "$COUNT" -gt 256 ]; then
+                  echo "::error::Matrix has $COUNT entries (limit: 256). Split into multiple workflows."
+                  exit 1
+                fi
+                echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+
+        test:
+          needs: generate-matrix
+          strategy:
+            matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
+          runs-on: ${{ matrix.os }}
+          steps:
+            - run: echo "Testing ${{ matrix.os }} / ${{ matrix.version }}"
+prevention:
+  - "Before adding a new matrix axis, calculate the new total job count — it must stay at or below 256."
+  - "For dynamic matrices (fromJSON), validate the output list length in the generator job and fail fast if > 256."
+  - "Prefer explicit include: lists over full Cartesian products when not all dimension combinations are meaningful."
+  - "Monitor matrix job counts over time: a previously-safe matrix silently crosses 256 as new versions are added."
+  - "Document the current job count in a comment next to the matrix block so reviewers notice when PRs push it higher."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/limits"
+    label: "GitHub Actions Limits — Job Matrix: 256 jobs per workflow run"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow"
+    label: "GitHub Docs — Using a matrix for your jobs"

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

@@ -0,0 +1,136 @@
+id: permissions-auth-070
+title: "GITHUB_TOKEN packages:write Cannot Delete GitHub Container Registry Packages"
+category: permissions-auth
+severity: error
+tags:
+  - github-packages
+  - ghcr
+  - container-registry
+  - packages-delete
+  - permissions
+  - pat
+patterns:
+  - regex: 'delete.*package.*403|package.*delete.*forbidden'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+  - "403 Forbidden"
+root_cause: |
+  GitHub Container Registry (ghcr.io) and other granular-permission package
+  registries (npm, NuGet, RubyGems on ghpr) use package-level access control
+  that is separate from repository permissions. The GITHUB_TOKEN workflow
+  permission block supports packages: write, which grants the ability to:
+  - Publish (push) new package versions
+  - Update package metadata and visibility
+
+  However, packages: write does NOT grant the ability to DELETE package
+  versions. Deletion of granular-permission packages requires the delete:packages
+  scope, which exists only on classic personal access tokens (PATs) — there is
+  no equivalent permission in the GITHUB_TOKEN fine-grained model.
+
+  As a result, workflows that use actions/delete-package-versions (or make
+  direct REST API calls to DELETE /user/packages/{type}/{name}/versions/{id}
+  or DELETE /orgs/{org}/packages/{type}/{package_name}/versions/{id}) always
+  fail with 403 "Resource not accessible by integration" even with:
+    permissions:
+      packages: write
+
+  Note: Repository-scoped packages (Apache Maven, legacy Gradle) that inherit
+  repository permissions may behave differently — deletion can work via the
+  repo admin role. Container Registry packages always use granular permissions.
+fix: |
+  Replace GITHUB_TOKEN with a token that carries delete:packages authority.
+
+  Option 1 (recommended for orgs): GitHub App token
+  - Create a GitHub App with "Packages: Read & Write" and "Packages: Admin"
+    permissions
+  - Install the app on the org or repo
+  - Use actions/create-github-app-token to generate a token in the workflow
+  - Pass the token to the deletion step
+
+  Option 2 (simpler for personal/small-team repos): Classic PAT
+  - Generate a classic PAT (Settings > Developer settings > Personal access
+    tokens > Tokens (classic)) with the delete:packages scope
+  - Store as a repository or organization secret
+  - Reference the secret in the deletion step
+
+  Option 3 (repo-scoped packages only — Apache Maven, Gradle):
+  - Ensure the package uses repository-scoped permissions (not granular)
+  - Grant the workflow admin access to the repository
+  - This does NOT apply to ghcr.io container images, which always require
+    a PAT or App approach for deletion
+fix_code:
+  - language: yaml
+    label: "Broken — GITHUB_TOKEN packages:write cannot delete container images"
+    code: |
+      permissions:
+        packages: write  # Grants publish access but NOT delete access
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Delete old versions
+              uses: actions/delete-package-versions@v5
+              with:
+                package-name: my-image
+                package-type: container
+                min-versions-to-keep: 5
+                token: ${{ secrets.GITHUB_TOKEN }}  # Fails with 403 for container packages
+
+  - language: yaml
+    label: "Fixed — classic PAT with delete:packages scope"
+    code: |
+      permissions:
+        packages: write
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Delete old versions
+              uses: actions/delete-package-versions@v5
+              with:
+                package-name: my-image
+                package-type: container
+                min-versions-to-keep: 5
+                # Classic PAT must have: write:packages + delete:packages scopes
+                token: ${{ secrets.PAT_DELETE_PACKAGES }}
+
+  - language: yaml
+    label: "Fixed — GitHub App token (recommended for organizations)"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.PACKAGE_CLEANUP_APP_ID }}
+                private-key: ${{ secrets.PACKAGE_CLEANUP_APP_KEY }}
+
+            - name: Delete old container image versions
+              uses: actions/delete-package-versions@v5
+              with:
+                package-name: my-image
+                package-type: container
+                min-versions-to-keep: 5
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "Never assume packages:write grants deletion rights — it only covers publish and metadata operations."
+  - "Provision a dedicated classic PAT or GitHub App with package admin access for all cleanup/retention workflows."
+  - "Document which secrets are needed for deletion workflows so maintainers do not accidentally replace them with GITHUB_TOKEN."
+  - "Audit all uses of actions/delete-package-versions in your org to confirm each workflow uses an appropriate token."
+  - "Prefer GitHub App tokens over classic PATs for org workflows — PAT credentials are tied to a specific user account."
+docs:
+  - url: "https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages"
+    label: "GitHub Docs — About permissions for GitHub Packages (granular vs repository-scoped)"
+  - url: "https://github.com/actions/delete-package-versions"
+    label: "actions/delete-package-versions — token requirements"
+  - url: "https://docs.github.com/en/rest/packages/packages"
+    label: "GitHub REST API — Packages DELETE endpoints"

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

@@ -0,0 +1,107 @@
+id: runner-environment-214
+title: 'setup-java Fails with "Invalid Version" for JetBrains Runtime 4-Part Semver (e.g. 17.0.8.1+1080.1)'
+category: runner-environment
+severity: error
+tags:
+  - setup-java
+  - jbr
+  - jetbrains-runtime
+  - java
+  - semver
+  - version-parsing
+  - windows
+  - ubuntu
+patterns:
+  - regex: 'Java setup process failed due to:\s*Invalid Version:\s*\d+\.\d+\.\d+\.\d+\+'
+    flags: 'i'
+  - regex: 'Invalid Version:\s*\d+\.\d+\.\d+\.\d+'
+    flags: 'i'
+  - regex: 'java setup.*failed.*Invalid Version'
+    flags: 'i'
+error_messages:
+  - 'Error: Java setup process failed due to: Invalid Version: 17.0.8.1+1080.1'
+  - 'Error: Java setup process failed due to: Invalid Version: 25.0.3+480.61'
+  - 'Error: Java setup process failed due to: Invalid Version: 21.0.5.1+1100.2'
+root_cause: |
+  JetBrains Runtime (JBR) version strings use a 4-part numeric format:
+  `major.minor.patch.update+build.sub-build` (e.g. `17.0.8.1+1080.1`).
+  This does NOT conform to standard semantic versioning (3-part numeric).
+
+  The `actions/setup-java` version resolver uses a semver parser internally.
+  When the user passes a full pinned JBR version string containing a 4-part
+  numeric prefix (the `.1` after the patch component), the parser throws:
+
+    "Invalid Version: 17.0.8.1+1080.1"
+
+  Affected distributions: `jetbrains` (JBR) distribution only.
+  Affected platforms: Ubuntu and Windows (both throw the same error).
+  Unaffected: Oracle, Temurin, Adopt, Corretto and other distributions whose
+  version strings use standard 3-part semver (e.g. `21.0.3+9`).
+
+  The root cause is that JBR independently versions patch updates
+  (the `.1` suffix), meaning a JBR patch release version is 4 integers deep,
+  which the bundled semver parser does not accept.
+
+  Tracked upstream: https://github.com/actions/setup-java/issues/1008 (open May 2026)
+  Fix PR: https://github.com/actions/setup-java/pull/1009 (isVersionSatisfies patch — pending merge)
+fix: |
+  Until https://github.com/actions/setup-java/pull/1009 is merged and released,
+  do NOT pin the full 4-part JBR version string. Use either:
+
+  1. The 3-part version prefix (major.minor.patch) — setup-java will resolve the
+     latest available JBR sub-build for that patch:
+
+       - uses: actions/setup-java@v5
+         with:
+           distribution: 'jetbrains'
+           java-version: '17.0.8'   # omit the .1 suffix
+
+  2. Just the major version for the latest JBR:
+
+       - uses: actions/setup-java@v5
+         with:
+           distribution: 'jetbrains'
+           java-version: '17'
+
+  3. The pre-release format accepted by the current parser (major.minor.patch
+     with the build metadata only, omitting the update digit):
+
+       - uses: actions/setup-java@v5
+         with:
+           distribution: 'jetbrains'
+           java-version: '17.0.8+1080.1'   # skip the 4th integer; use build metadata
+fix_code:
+  - language: yaml
+    label: 'Use 3-part version prefix to avoid "Invalid Version" on JBR'
+    code: |
+      - name: Set up JBR 17 (JetBrains Runtime)
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'jetbrains'
+          java-version: '17.0.8'   # NOT '17.0.8.1+1080.1' — 4-part fails the parser
+  - language: yaml
+    label: 'Major-version pin (simplest, always resolves latest JBR for that major)'
+    code: |
+      - name: Set up JBR 25
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'jetbrains'
+          java-version: '25'
+prevention:
+  - 'Check the JBR releases page to understand the version format before pinning.
+    JBR versions are `major.minor.patch.update+build.sub-build`; only use the
+    3-part prefix (major.minor.patch) or major-version-only with setup-java.'
+  - 'Watch https://github.com/actions/setup-java/pull/1009 for when the fix merges
+    so full 4-part JBR version strings become accepted.'
+  - 'For reproducibility without pinning the exact JBR sub-build, consider
+    using a `.java-version` file with a 3-part version string and referencing it
+    via `java-version-file:` in setup-java.'
+docs:
+  - url: 'https://github.com/actions/setup-java/issues/1008'
+    label: 'setup-java #1008 — Error parsing JBR version 17.0.8.1+1080.1 (open, May 2026)'
+  - url: 'https://github.com/actions/setup-java/pull/1009'
+    label: 'setup-java PR #1009 — fix: reject non-semver candidate versions in isVersionSatisfies (pending)'
+  - url: 'https://github.com/actions/setup-java?tab=readme-ov-file#supported-distributions'
+    label: 'setup-java README — Supported distributions (JetBrains / JBR)'
+  - url: 'https://github.com/JetBrains/JetBrainsRuntime/releases'
+    label: 'JetBrains Runtime releases — version format reference'

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

@@ -0,0 +1,93 @@
+id: runner-environment-215
+title: 'setup-node fails with EBADDEVENGINES when devEngines.packageManager.version does not match initial npm'
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - npm
+  - devEngines
+  - EBADDEVENGINES
+  - package-manager
+  - npm-version
+patterns:
+  - regex: 'npm error code EBADDEVENGINES'
+    flags: 'i'
+  - regex: 'npm error EBADDEVENGINES.*Invalid devEngines\.packageManager'
+    flags: 'i'
+  - regex: 'npm error EBADDEVENGINES.*Invalid semver version.*does not match.*for "packageManager"'
+    flags: 'i'
+  - regex: '/npm config get cache\s*npm error code EBADDEVENGINES'
+    flags: 'is'
+error_messages:
+  - 'npm error code EBADDEVENGINES'
+  - 'npm error EBADDEVENGINES The developer of this package has specified the following through devEngines'
+  - 'npm error EBADDEVENGINES Invalid devEngines.packageManager'
+  - 'npm error EBADDEVENGINES Invalid semver version "^11.10.0" does not match "10.9.7" for "packageManager"'
+root_cause: |
+  actions/setup-node@v6 runs `npm config get cache` immediately after installing Node.js to
+  determine the npm cache path before activating the package-manager-cache feature. If
+  package.json declares a `devEngines.packageManager.version` constraint (Node.js 22.6+
+  feature) that the bundled npm does NOT satisfy, npm exits with EBADDEVENGINES before
+  returning the cache path.
+
+  The failure happens before setup-node has a chance to upgrade npm to the required version,
+  creating a catch-22: the action needs the cache path to set up, but npm won't answer
+  because the version constraint is not yet met.
+
+  Common scenario: project requires `npm@^11.10.0` (for `min-release-age` or other features
+  added in npm 11.x), but Node 22 ships with npm 10.x. The first `npm` invocation fails
+  immediately when devEngines enforcement is active.
+fix: |
+  Option 1 (recommended) — add `"onFail": "warn"` to the devEngines.packageManager block.
+  This downgrades version mismatches to warnings so npm commands still complete, letting
+  setup-node finish. Install the required npm version in a subsequent step.
+
+  Option 2 — pin Node.js to a version whose bundled npm satisfies devEngines (often
+  impractical).
+
+  Option 3 — set `package-manager-cache: false` in setup-node to skip the cache-path probe
+  entirely and manage npm caching separately.
+fix_code:
+  - language: yaml
+    label: 'Option 1 — add onFail: warn to package.json (fix the root cause)'
+    code: |
+      # In package.json:
+      # {
+      #   "devEngines": {
+      #     "packageManager": {
+      #       "name": "npm",
+      #       "version": "^11.10.0",
+      #       "onFail": "warn"        <-- add this
+      #     }
+      #   }
+      # }
+
+      # In workflow — install the required npm version after setup-node succeeds:
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+      - run: npm install -g npm@^11.10.0
+  - language: yaml
+    label: 'Option 3 — disable package-manager-cache in setup-node'
+    code: |
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          package-manager-cache: false   # skip npm config get cache probe
+      - run: npm install -g npm@^11.10.0
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - 'Always pair devEngines.packageManager.version with "onFail": "warn" unless the project must hard-fail on CI for version mismatches.'
+  - 'Use package-manager-cache: false in setup-node and handle npm caching manually when devEngines constraints are strict.'
+  - 'Track the Node.js release schedule to choose a version that ships with an npm satisfying devEngines requirements from day one.'
+  - 'Pin action version in workflow (e.g., actions/setup-node@v6.4.0) and test upgrades in a branch before rolling out.'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1553'
+    label: 'setup-node#1553 — EBADDEVENGINES blocks cache-path probe (May 2026)'
+  - url: 'https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devengines'
+    label: 'npm docs — devEngines field and onFail option'
+  - url: 'https://github.com/nodejs/node/issues/62425'
+    label: 'Node.js#62425 — npm installation behavior on Node v22.22.2 with devEngines'

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

@@ -0,0 +1,82 @@
+id: runner-environment-216
+title: 'ubuntu-26.04 ships Helm 4 — `helm repo add --no-update` removed, causes unknown flag error'
+category: runner-environment
+severity: error
+tags:
+  - helm
+  - helm-4
+  - ubuntu-26
+  - tool-upgrade
+  - flag-removed
+patterns:
+  - regex: 'Error: unknown flag: --no-update'
+    flags: 'i'
+  - regex: 'unknown flag.*--no-update'
+    flags: 'i'
+error_messages:
+  - 'Error: unknown flag: --no-update'
+  - 'Error: flag provided but not defined: --no-update'
+root_cause: |
+  ubuntu-26.04 runner images install Helm 4 (via the `get-helm-4` installer script)
+  instead of Helm 3 used on ubuntu-22.04 and ubuntu-24.04. In Helm 4, the
+  `--no-update` flag was permanently removed from `helm repo add`
+  (breaking change: helm/helm#13614, released in Helm v4.0.0, November 2025).
+
+  In Helm 3, `helm repo add <name> <url> --no-update` was used to add a repo
+  without triggering a refresh of all configured repos. This was common in CI
+  pipelines to speed up `helm repo add` when many repos are configured. The
+  flag was first deprecated in Helm 3.7 and has been removed entirely in Helm 4
+  with no deprecated alias retained.
+
+  The runner-images commit 9e3319d (May 2026) introduced Helm 4 for ubuntu-26.04.
+  Any workflow using `runs-on: ubuntu-26.04` (or eventually `ubuntu-latest` when
+  it migrates to 26.04) that calls `helm repo add --no-update` will fail
+  immediately with `Error: unknown flag: --no-update`.
+fix: |
+  Remove the `--no-update` flag entirely. In Helm 4, `helm repo add` does not
+  update existing repos by default — the behavior the flag used to enforce is
+  now the default behavior.
+
+  If you need to force-update all repos after adding, use `helm repo update`.
+
+  To avoid Helm version surprises on ubuntu-26.04, pin a specific Helm version
+  using `azure/setup-helm` and pass the version explicitly.
+fix_code:
+  - language: yaml
+    label: 'Remove --no-update flag (Helm 4 default behavior)'
+    code: |
+      - name: Add Helm repo
+        run: |
+          # Helm 4 on ubuntu-26.04: --no-update flag has been removed.
+          # Helm 4 does not update existing repos by default (old --no-update behavior).
+          # Simply omit the flag:
+          helm repo add bitnami https://charts.bitnami.com/bitnami
+          # If you still need to update all repos afterwards:
+          # helm repo update
+
+  - language: yaml
+    label: 'Pin Helm version with azure/setup-helm to avoid version surprises'
+    code: |
+      - name: Set up Helm
+        uses: azure/setup-helm@v5
+        with:
+          version: '3.17.x'   # Pin to Helm 3 if your workflow isn't Helm 4 ready
+          # Or pin to a specific Helm 4 version:
+          # version: '4.2.x'
+
+      - name: Add Helm repo
+        run: helm repo add bitnami https://charts.bitnami.com/bitnami
+prevention:
+  - "Pin your Helm version with `azure/setup-helm` rather than relying on the pre-installed Helm on the runner."
+  - "When migrating to ubuntu-26.04, audit all `helm repo add` calls and remove any `--no-update` flags."
+  - "Check the Helm 4 migration guide at https://helm.sh/docs/topics/v4_migration/ before adopting ubuntu-26.04."
+  - "Add a CI step that prints `helm version` so version surprises are immediately visible in logs."
+docs:
+  - url: 'https://github.com/helm/helm/blob/main/CHANGELOG.md'
+    label: 'Helm 4 Changelog — breaking changes'
+  - url: 'https://helm.sh/docs/topics/v4_migration/'
+    label: 'Helm v4 Migration Guide'
+  - url: 'https://github.com/actions/runner-images/commit/9e3319d6b4acc306925295853d0ff41ddd5c40f0'
+    label: 'runner-images commit: ubuntu-26 ships Helm 4 (get-helm-4)'
+  - url: 'https://github.com/Azure/setup-helm'
+    label: 'azure/setup-helm action — pin Helm version'