@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/runner-environment/github-script-v6-octokit-rest-actions-not-function.yml

@@ -0,0 +1,87 @@
+id: runner-environment-047
+title: "actions/github-script@v6 octokit.rest.actions.* Methods Not Available (Stale Octokit Bundle)"
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - octokit
+  - rest-api
+  - variables-api
+  - actions-api
+  - version-mismatch
+patterns:
+  - regex: "github\\.rest\\.actions\\.[a-zA-Z]+ is not a function"
+    flags: "i"
+  - regex: "TypeError.*github\\.rest\\.actions\\."
+    flags: "i"
+  - regex: "Unhandled error: TypeError.*github\\.rest\\."
+    flags: "i"
+error_messages:
+  - "TypeError: github.rest.actions.createRepoVariable is not a function"
+  - "TypeError: github.rest.actions.listRepoVariables is not a function"
+  - "TypeError: github.rest.actions.getEnvironmentVariable is not a function"
+  - "TypeError: github.rest.actions.updateRepoVariable is not a function"
+  - "Unhandled error: TypeError: github.rest.actions.createOrUpdateRepoVariable is not a function"
+root_cause: |
+  `actions/github-script@v6` bundles `@octokit/plugin-rest-endpoint-methods` v6.3.0, which
+  predates GitHub's Variables API endpoints and several other newer REST endpoints added to the
+  GitHub API in 2023. These methods were added to the Octokit plugin in v6.8.0+.
+
+  When a workflow step calls `github.rest.actions.createRepoVariable()`,
+  `github.rest.actions.listRepoVariables()`, `github.rest.actions.listEnvironmentVariables()`,
+  or other Variables API methods, these functions simply do not exist in the bundled octokit
+  inside `github-script@v6`. JavaScript returns `undefined` when accessing the property, and
+  attempting to call it throws a `TypeError: X is not a function` that fails the step immediately.
+
+  The workflow log shows the TypeError and a non-zero exit code. The confusing part is that the
+  GitHub REST API itself fully supports these endpoints — the failure is an action version issue,
+  not an API permission or token scope issue.
+fix: |
+  Upgrade to `actions/github-script@v7`, which ships with a significantly newer version of
+  `@octokit/plugin-rest-endpoint-methods` that includes the Variables API and all other
+  endpoints added since 2023. As a workaround when staying on v6, use `github.request()`
+  with the raw REST endpoint path to call any API method directly, bypassing the typed wrapper.
+fix_code:
+  - language: yaml
+    label: "Upgrade to github-script@v7 (recommended)"
+    code: |
+      - uses: actions/github-script@v7   # v7 ships updated @octokit/plugin-rest-endpoint-methods
+        with:
+          script: |
+            await github.rest.actions.createRepoVariable({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'MY_VAR',
+              value: 'my-value'
+            });
+  - language: yaml
+    label: "Workaround for v6: use github.request() with raw REST path"
+    code: |
+      - uses: actions/github-script@v6
+        with:
+          script: |
+            // Use github.request() directly — bypasses the typed wrapper
+            await github.request('POST /repos/{owner}/{repo}/actions/variables', {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'MY_VAR',
+              value: 'my-value'
+            });
+
+            // List variables example
+            const { data } = await github.request(
+              'GET /repos/{owner}/{repo}/actions/variables',
+              { owner: context.repo.owner, repo: context.repo.repo }
+            );
+            console.log(data.variables);
+prevention:
+  - "Pin to `actions/github-script@v7` or later for any workflow using Variables API or other endpoints added after mid-2022"
+  - "When adding a new `github.rest.*` call, verify the method exists in the action version's bundled octokit before deploying"
+  - "Use `github.request()` with raw REST paths as a version-independent fallback for any endpoint call"
+docs:
+  - url: "https://github.com/actions/github-script/issues/345"
+    label: "actions/github-script#345 — octokit.rest.actions not available"
+  - url: "https://github.com/actions/github-script/releases/tag/v7.0.0"
+    label: "actions/github-script v7.0.0 release — updated @octokit/plugin-rest-endpoint-methods"
+  - url: "https://octokit.github.io/rest.js/v18/#actions"
+    label: "Octokit REST.js — actions endpoints reference"

package/errors/runner-environment/macos-15-mono-nuget-removed.yml

@@ -0,0 +1,151 @@
+id: runner-environment-044
+title: "macOS-15 Runner Removes Mono, NuGet, and NUnit — Workflows Using These Tools Break"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-15
+  - mono
+  - nuget
+  - nunit
+  - runner-image
+  - breaking-change
+  - macos-latest
+patterns:
+  - regex: "mono.*not found|The term 'mono' is not recognized|command not found.*mono"
+    flags: "i"
+  - regex: "nuget.*not found|command not found.*nuget|NuGet.*is not recognized"
+    flags: "i"
+  - regex: "nunit.*not found|command not found.*nunit-console|nunit3-console.*not recognized"
+    flags: "i"
+  - regex: "Error.*Mono runtime.*could not be found|Unable to find mono"
+    flags: "i"
+error_messages:
+  - "bash: mono: command not found"
+  - "The term 'mono' is not recognized as the name of a cmdlet, function, script file, or executable program."
+  - "bash: nuget: command not found"
+  - "bash: nunit-console: command not found"
+  - "Error: Unable to locate executable file: 'mono'"
+root_cause: |
+  GitHub Actions migrated `macos-latest` from macOS 14 (Sonoma) to macOS 15 (Sequoia)
+  beginning August 4, 2025, completing by August 30, 2025. The macOS-15 image was rebuilt
+  from scratch and intentionally excludes several tools that were present in macOS-14:
+
+  - **Mono 6.12.x** — removed from macOS-15 images "due to maintenance reasons"
+  - **NuGet 6.3.x** — removed from macOS-15 images "due to maintenance reasons"
+  - **NUnit 6.15.4** — removed from macOS-15 images "due to maintenance reasons"
+
+  Any workflow pinned to `macos-latest` that calls `mono`, `nuget`, or `nunit-console`
+  directly (without an install step) will fail immediately with a "command not found" error
+  after the migration. Workflows that explicitly pin `macos-14` are unaffected but will
+  need to migrate before macOS-14 reaches its retirement date (November 2, 2026).
+
+  These removals were announced alongside the macOS-15 migration notice in
+  runner-images#12520. The decision was driven by the Mono project's reduced maintenance
+  status and the availability of .NET cross-platform alternatives.
+
+  Other notable differences between macOS-14 and macOS-15 that may cause indirect failures:
+  - **Clang/LLVM (Xcode)**: 15.x → 16.x (compiler version bump, stricter warnings)
+  - **Clang/LLVM (Homebrew)**: 15.x → 18.x
+  - **Node.js default**: 20.x → 22.x
+fix: |
+  **For Mono-dependent workflows** — install Mono explicitly or migrate to .NET:
+
+  Option 1: Install Mono in the workflow step before using it:
+  ```yaml
+  - name: Install Mono
+    run: brew install mono
+  ```
+
+  Option 2: Migrate to .NET 9/10 (recommended long-term):
+  Replace `mono myapp.exe` with a .NET-native build. Mono is in maintenance mode;
+  .NET is the supported cross-platform runtime going forward.
+
+  **For NuGet** — use `dotnet nuget` instead:
+  The .NET CLI includes full NuGet support. Replace standalone `nuget` calls with
+  `dotnet restore`, `dotnet nuget push`, etc.
+
+  **For NUnit** — use the .NET test runner:
+  Replace `nunit-console` with `dotnet test`. The NUnit test adapter integrates
+  with `dotnet test` out of the box.
+
+  **Pin to macOS-14 temporarily** (bridging strategy, not long-term):
+  ```yaml
+  runs-on: macos-14
+  ```
+  macOS-14 retires November 2, 2026 — plan your migration before then.
+fix_code:
+  - language: yaml
+    label: "Install Mono via Homebrew on macOS-15"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # macOS-15
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Mono
+              run: brew install mono
+
+            - name: Build with Mono
+              run: mono build.exe
+  - language: yaml
+    label: "Migrate from nuget CLI to dotnet nuget"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '9.x'
+
+            # Before: nuget restore MySolution.sln
+            # After:
+            - name: Restore dependencies
+              run: dotnet restore MySolution.sln
+
+            # Before: nuget push *.nupkg -Source https://api.nuget.org/v3/index.json
+            # After:
+            - name: Publish package
+              run: dotnet nuget push "**/*.nupkg" --source https://api.nuget.org/v3/index.json
+  - language: yaml
+    label: "Migrate from nunit-console to dotnet test"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '9.x'
+
+            # Before: nunit-console MyProject.Tests.dll
+            # After:
+            - name: Run tests
+              run: dotnet test MyProject.Tests/MyProject.Tests.csproj --logger "trx"
+  - language: yaml
+    label: "Pin to macos-14 as short-term bridge"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-14   # Mono/NuGet/NUnit still available; retires Nov 2026
+          steps:
+            - uses: actions/checkout@v4
+            # ... existing workflow unchanged ...
+prevention:
+  - "Never rely on pre-installed Mono, NuGet, or NUnit on macOS runners — always use setup steps (`dotnet`, `brew install mono`) for explicit dependency management."
+  - "Subscribe to actions/runner-images announcements (issues labeled 'Announcement') to receive advance notice of macOS-latest label migrations."
+  - "Use `macos-15` or `macos-latest` with explicit install steps for any tooling beyond the core macOS toolchain."
+  - "Migrate Mono/.NET Framework projects to .NET 9/10 — Mono is in maintenance mode and will continue to lose runner support."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12520"
+    label: "runner-images#12520: macOS-latest will use macOS-15 in August 2025 — tool removal table"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS-15 runner image README — installed software"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs: About GitHub-hosted runners"

package/errors/runner-environment/macos-15-xcode-simulator-sdk-policy.yml

@@ -0,0 +1,141 @@
+id: runner-environment-045
+title: "macOS-15 Removes Old Xcode Simulator SDKs — Only 3 Latest Xcode Versions Keep Platform Tools"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-15
+  - xcode
+  - ios
+  - simulator
+  - sdk
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: "Requested.*simulator runtime.*not available|Could not find.*runtime.*for.*platform"
+    flags: "i"
+  - regex: "iphonesimulator.*SDK.*not found|No such SDK.*iphonesimulator"
+    flags: "i"
+  - regex: "error.*tvos.*simulator.*not.*installed|watchos.*sdk.*unavailable"
+    flags: "i"
+  - regex: "xcodebuild.*error.*platform.*version.*not.*installed"
+    flags: "i"
+  - regex: "Simulator runtime.*not installed.*for destination"
+    flags: "i"
+error_messages:
+  - "xcodebuild: error: SDK 'iphonesimulator17.0' cannot be located."
+  - "error: The requested simulator runtime is not installed."
+  - "xcodebuild: error: Unable to find a destination matching the provided destination specifier"
+  - "Could not find the tvOS simulator runtime for the version specified."
+  - "Requested runtime 'com.apple.CoreSimulator.SimRuntime.watchOS-10-0' was not found."
+root_cause: |
+  Beginning August 11, 2025, GitHub Actions macOS-15 (and later) runner images changed
+  their Xcode platform support policy: **only the three most recently installed Xcode versions
+  retain their platform tools** (SDK and simulator runtimes for iOS, tvOS, watchOS, visionOS).
+  Older Xcode versions remain on the image but have their simulator runtimes removed to
+  reclaim disk space.
+
+  The motivation was severe disk pressure on macOS runners caused by visionOS simulator
+  runtimes. Each Xcode version ships multiple runtimes (iOS, watchOS, tvOS, visionOS), and
+  keeping them for every installed Xcode version was exhausting the fixed disk allocation.
+
+  **Practical impact for macOS-15 images:**
+  The macOS-15 image ships with Xcode versions 16.0, 16.2, 16.3, 16.4, and 26.0 Beta
+  (as of mid-2026). Only the three most recent (16.3, 16.4, 26.0 Beta) retain full platform
+  tools. Workflows that target iOS 17.x or earlier simulators (which required Xcode ≤ 16.1)
+  will fail because those simulator runtimes are no longer present.
+
+  Workflows pinned to `macos-14` are unaffected but must migrate before macOS-14 retires
+  (November 2, 2026). The policy does NOT apply to macOS-13 or macOS-14 images — only
+  macOS-15 and newer.
+
+  Source: actions/runner-images#12541 (announced July 8, 2025; deployed August 11, 2025)
+fix: |
+  **Option 1 — Upgrade your minimum deployment target** (recommended):
+  If your app targets iOS 17.x or earlier purely for historical support, update the
+  `IPHONEOS_DEPLOYMENT_TARGET` in your Xcode project to 18.x (iOS 18 = Xcode 16.x).
+  Modern apps rarely need to support OS versions older than what Xcode's latest SDK covers.
+
+  **Option 2 — Use xcode-select to pin a supported Xcode version**:
+  Check which Xcode versions have full platform tools on the macOS-15 image
+  (the README lists them), then use the correct destination syntax:
+
+  ```yaml
+  - name: Select Xcode 16.4
+    run: sudo xcode-select -s /Applications/Xcode_16.4.app
+  ```
+
+  **Option 3 — Test on device targets instead of simulators**:
+  If your CI only needs to build (not run on simulator), use `generic/platform=iOS`
+  instead of specifying a simulator runtime version.
+
+  **Option 4 — Install missing runtimes** (not recommended — slow, fragile):
+  You can download and install older simulator runtimes via `xcodebuild -downloadPlatform`
+  but this is time-consuming (~5-10 min) and fragile in CI.
+fix_code:
+  - language: yaml
+    label: "Pin to a supported Xcode version with full platform tools"
+    code: |
+      jobs:
+        test-ios:
+          runs-on: macos-latest   # macOS-15
+          steps:
+            - uses: actions/checkout@v4
+
+            # Select Xcode with full platform tools (check macos-15 README for current list)
+            - name: Select Xcode 16.4
+              run: sudo xcode-select -s /Applications/Xcode_16.4.app
+
+            - name: Build and Test
+              run: |
+                xcodebuild test \
+                  -scheme MyApp \
+                  -destination 'platform=iOS Simulator,name=iPhone 16,OS=18.4' \
+                  CODE_SIGN_IDENTITY="" \
+                  CODE_SIGNING_REQUIRED=NO
+  - language: yaml
+    label: "Build without specifying simulator runtime (avoids SDK lookup)"
+    code: |
+      jobs:
+        build-ios:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build for generic iOS (no simulator runtime needed)
+              run: |
+                xcodebuild build \
+                  -scheme MyApp \
+                  -destination 'generic/platform=iOS' \
+                  CODE_SIGN_IDENTITY="" \
+                  CODE_SIGNING_REQUIRED=NO
+  - language: yaml
+    label: "Use a matrix to target only Xcode versions with platform tools"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          strategy:
+            matrix:
+              # Only include Xcode versions that have full platform tools on macOS-15
+              xcode: ['16.3', '16.4', '26.0']
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Select Xcode ${{ matrix.xcode }}
+              run: sudo xcode-select -s /Applications/Xcode_${{ matrix.xcode }}.app
+
+            - name: Test
+              run: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,OS=latest,name=iPhone 16'
+prevention:
+  - "Check the macOS runner README (linked below) to see which Xcode versions have full platform tools before writing xcodebuild destinations."
+  - "Avoid specifying old iOS/watchOS/tvOS SDK versions in xcodebuild -destination — always use 'OS=latest' or a version compatible with the most recent 3 Xcode releases."
+  - "Subscribe to runner-images announcements so you know which Xcode versions have platform tools on each image before they ship."
+  - "Don't hardcode simulator runtime versions — derive them from the Xcode version you're selecting."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12541"
+    label: "runner-images#12541: Xcode platform tools support policy change announcement"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS-15 runner README — Xcode versions and installed SDKs"
+  - url: "https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes"
+    label: "Apple Docs: Installing additional simulator runtimes"

package/errors/runner-environment/runner-oom-exit-code-137.yml

@@ -0,0 +1,117 @@
+id: runner-environment-038
+title: "Runner Job Killed with Exit Code 137 (Out of Memory / OOM Kill)"
+category: runner-environment
+severity: error
+tags:
+  - oom
+  - exit-code-137
+  - memory
+  - killed
+  - sigkill
+  - runner
+patterns:
+  - regex: "Process completed with exit code 137"
+    flags: "i"
+  - regex: "runner has received a shutdown signal"
+    flags: "i"
+  - regex: "The hosted runner.*lost communication with the server"
+    flags: "i"
+  - regex: "Killed\\s*$"
+    flags: "im"
+error_messages:
+  - "Process completed with exit code 137."
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+  - "The hosted runner: GitHub Actions N runner lost communication with the server. Anything after this message may not be captured."
+  - "Killed"
+root_cause: |
+  Exit code 137 on Linux is 128 + signal 9 (SIGKILL), meaning the process was forcibly
+  terminated by the operating system's OOM (Out of Memory) killer. This happens when a process
+  or the runner VM exhausts available memory and the kernel kills it to recover resources.
+
+  GitHub-hosted runner memory allocations (standard runners):
+  - ubuntu-*/windows-*: 16 GB RAM, 14 GB swap
+  - macos-*: 14 GB RAM (Apple Silicon)
+  - Large runners: 32–64 GB depending on tier
+
+  Common root causes:
+  - JVM tools (Gradle, Maven, Kotlin compiler) defaulting to large heap fractions without
+    explicit -Xmx caps (JVM defaults to up to 25% of system RAM for heap)
+  - Node.js webpack/esbuild bundling large codebases without --max-old-space-size cap
+  - Docker build stages that cache too many layers in memory simultaneously
+  - Test suites with memory leaks that accumulate across hundreds of test cases
+  - cargo/rustc compilation with many parallel units (-j) exceeding available memory
+  - Multiple matrix jobs on a shared self-hosted runner competing for the same memory pool
+
+  The "runner has received a shutdown signal" message is a related pattern that can occur
+  when the runner VM is preempted by GitHub's infrastructure (less common, transient).
+fix: |
+  Option 1 — Cap memory for known heavy tools:
+  - JVM: Set JAVA_OPTS="-Xmx4g -Xms512m" and GRADLE_OPTS="-Xmx4g -Dorg.gradle.daemon=false"
+  - Node.js: Set NODE_OPTIONS="--max-old-space-size=4096"
+  - Rust: Set CARGO_BUILD_JOBS to limit parallel compilation units
+
+  Option 2 — Free memory before intensive steps:
+  - Drop OS page cache: sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches'
+  - Use jlumbroso/free-disk-space action to reclaim space used by pre-installed tools
+
+  Option 3 — Upgrade runner size:
+  - Switch to ubuntu-latest-16-cores (64 GB RAM) for memory-intensive builds
+
+  Option 4 — For transient infrastructure OOM kills:
+  - Simply re-run the failed job — these are often one-off events
+  - Add workflow-level retry for idempotent builds
+fix_code:
+  - language: yaml
+    label: "Cap JVM and Node.js memory to prevent OOM kills"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            JAVA_OPTS: "-Xmx4g -Xms512m"
+            GRADLE_OPTS: "-Xmx4g -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=2"
+            NODE_OPTIONS: "--max-old-space-size=4096"
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Free OS page cache
+              run: sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches' || true
+
+            - name: Build
+              run: ./gradlew build
+  - language: yaml
+    label: "Use a larger runner for memory-intensive builds"
+    code: |
+      jobs:
+        build:
+          # Standard: ubuntu-latest = 16 GB RAM
+          # Large runners require billing configuration
+          runs-on: ubuntu-latest-16-cores  # 64 GB RAM
+          steps:
+            - uses: actions/checkout@v4
+            - run: make all
+  - language: yaml
+    label: "Debug memory usage before OOM occurs"
+    code: |
+      - name: Check available memory
+        run: |
+          echo "=== Free memory ==="
+          free -h
+          echo "=== /proc/meminfo ==="
+          grep -E "MemTotal|MemFree|MemAvailable|SwapTotal|SwapFree" /proc/meminfo
+prevention:
+  - "Always set explicit heap caps for JVM-based tools (JAVA_OPTS, GRADLE_OPTS) — never rely on the JVM's auto-detection of available memory."
+  - "Add NODE_OPTIONS=--max-old-space-size=4096 for Node.js build tools processing large codebases."
+  - "Add a 'free memory' step early in memory-intensive jobs using `echo 3 > /proc/sys/vm/drop_caches`."
+  - "Profile memory with `free -h` at start and end of build phases to catch accumulation before hitting the limit."
+  - "Consider the jlumbroso/free-disk-space action which also frees memory by removing unused pre-installed tools."
+  - "For self-hosted runners, set memory limits per job via systemd slice or cgroup to prevent one job from OOM-killing others."
+docs:
+  - url: "https://github.com/actions/runner/issues/3724"
+    label: "actions/runner #3724 — runner shutdown signal reports"
+  - url: "https://github.com/orgs/community/discussions/188508"
+    label: "Community discussion #188508 — unexpected job cancellations and OOM"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub-hosted runner hardware resources"
+  - url: "https://stackoverflow.com/questions/72489714/github-actions-job-cancelled-for-no-obvious-reason"
+    label: "Stack Overflow — job cancelled with no obvious reason (exit 137)"

package/errors/runner-environment/setup-go-go123-telemetry-cache-failure.yml

@@ -0,0 +1,92 @@
+id: runner-environment-041
+title: "actions/setup-go Go 1.23 Module Cache Restore Fails — Tar Extraction Error on Telemetry Files"
+category: runner-environment
+severity: error
+tags:
+  - actions/setup-go
+  - go
+  - go-1.23
+  - cache
+  - tar
+  - telemetry
+  - module-cache
+patterns:
+  - regex: "Cannot open: File exists"
+    flags: "i"
+  - regex: "tar.*failed with exit code 2|exit code 2.*tar"
+    flags: "i"
+  - regex: "Failed to restore.*usr/bin/tar.*failed"
+    flags: "i"
+  - regex: "golang\\.org/x/telemetry.*File exists"
+    flags: "i"
+error_messages:
+  - "/usr/bin/tar: ../../../go/pkg/mod/golang.org/x/telemetry/config@v0.31.0/config.json: Cannot open: File exists"
+  - "/usr/bin/tar: Exiting with failure status due to previous errors"
+  - "Warning: Failed to restore: \"/usr/bin/tar\" failed with error: The process '/usr/bin/tar' failed with exit code 2"
+  - "Cache is not found"
+root_cause: |
+  Go 1.23.0 introduced a telemetry subsystem that writes configuration files into the
+  module cache at `$GOPATH/pkg/mod/golang.org/x/telemetry/`. When `actions/setup-go`
+  attempts to restore a previously saved module cache, `tar` fails to extract these
+  telemetry files because they **already exist** on the runner filesystem from the
+  Go toolchain installation step.
+
+  The collision happens because:
+  1. `actions/setup-go` installs Go 1.23.0 (which creates telemetry files in the
+     module cache directory during toolchain initialization)
+  2. When restoring the cached module archive, `tar` attempts to write the same
+     telemetry files and hits "Cannot open: File exists" for each conflicting path
+  3. `tar` exits with code 2, causing the cache restore to report failure
+  4. The module cache falls back to a full fresh download — wasting CI minutes
+
+  This was a regression introduced in Go 1.23.0 and fixed in Go 1.23.1 by adjusting
+  how the telemetry module integrates with the module cache to avoid the path collision.
+
+  Source: actions/setup-go issue #506
+fix: |
+  **Upgrade to Go 1.23.1 or later** — the fix was shipped in the patch release.
+  Pin `go-version` to `>=1.23.1` in your `actions/setup-go` step.
+
+  If you must remain on 1.23.0 temporarily, the workaround is to delete the conflicting
+  telemetry directory before the cache restore runs, or to disable module cache caching
+  entirely for affected workflows until you can upgrade.
+fix_code:
+  - language: yaml
+    label: "Fixed — pin to Go 1.23.1+ to avoid the telemetry cache collision"
+    code: |
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23.1'   # 1.23.0 has the tar collision bug; 1.23.1+ is fixed
+          cache: true
+  - language: yaml
+    label: "Fixed — use go-version-file to inherit version from go.mod"
+    code: |
+      # ✅ RECOMMENDED: source version from go.mod so the workflow stays in sync automatically
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod   # reads the version from the go directive in go.mod
+          cache: true
+          # Ensure go.mod specifies 'go 1.23.1' or later to avoid the cache bug
+  - language: yaml
+    label: "Workaround — clear telemetry before cache restore (Go 1.23.0 only)"
+    code: |
+      # Workaround if stuck on Go 1.23.0: pre-remove telemetry path before setup-go
+      - name: Clear stale telemetry module cache
+        run: rm -rf ~/go/pkg/mod/golang.org/x/telemetry || true
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23.0'
+          cache: true
+prevention:
+  - "Pin `go-version` to patch releases (e.g., `1.23.1`) rather than minor versions (e.g., `1.23`) to avoid picking up newly released patch versions with regressions before they are fixed."
+  - "Use `go-version-file: go.mod` to keep CI and local development in sync — update go.mod to `go 1.23.1` or later."
+  - "Monitor `actions/setup-go` releases for patch notes when upgrading across Go minor versions."
+  - "If cache restore fails with tar errors, check if the error involves newly introduced toolchain files that collide with the restore path."
+docs:
+  - url: "https://github.com/actions/setup-go/issues/506"
+    label: "actions/setup-go issue #506 — Go 1.23 telemetry cache tar collision"
+  - url: "https://github.com/actions/setup-go"
+    label: "actions/setup-go repository"
+  - url: "https://go.dev/doc/devel/release#go1.23.minor"
+    label: "Go 1.23 release notes and minor releases"