@htekdev/actions-debugger 1.0.111 → 1.0.113

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

@@ -0,0 +1,114 @@
+id: runner-environment-181
+title: 'Self-hosted Windows runner steps stuck "Waiting for a runner to pick up this job..." mid-job after v2.321.0 auto-update'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - windows
+  - runner-update
+  - stuck
+  - queued
+  - multi-step
+  - message-queue
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+  - regex: 'Current runner version.*2\.32[1-9]|v2\.32[1-9]\.'
+    flags: 'i'
+error_messages:
+  - "Waiting for a runner to pick up this job..."
+root_cause: |
+  After the GitHub Actions runner auto-updated to v2.321.0 (released November 2024),
+  Windows self-hosted runners began exhibiting a specific failure mode in multi-step
+  jobs: the first step of a job executes successfully, but subsequent steps hang
+  indefinitely in a queued state showing "Waiting for a runner to pick up this job..."
+
+  Root cause: The v2.321.0 update introduced a regression in the Windows runner's
+  inter-step message queue session management. After completing a step, the runner
+  sends a completion signal to the GitHub broker but fails to maintain the job session
+  channel open for the next step. GitHub's broker interprets the broken session as
+  the job needing a fresh runner allocation — hence the "waiting for runner" message
+  for a job that is technically already in-flight.
+
+  The runner service itself remains running and reports "idle" to GitHub, but the job
+  session token has already been invalidated or the queue socket closed. Restarting
+  the runner service re-establishes the connection and any subsequent cancel+rerun
+  immediately picks up because the session management is freshly initialized.
+
+  Characteristics:
+  - Specific to Windows self-hosted runners (not Ubuntu/macOS hosted runners)
+  - Only occurs in jobs with 2 or more steps
+  - Step 1 always completes; step 2+ hangs without timeout
+  - Cancel + rerun of the stuck job resolves it immediately
+  - Runner service restart also resolves it
+  - Began appearing after Nov 27, 2024 auto-update on Windows machines
+  - Still open as of May 2026 with 90+ reactions (actions/runner#3609)
+
+  Note: This is distinct from runner-environment-082 (runner stuck between JOBS in
+  the same workflow) — this failure occurs between STEPS within a single job.
+fix: |
+  Immediate mitigation:
+  1. Cancel the stuck run in the GitHub Actions UI and re-run it — the job typically
+     completes correctly on rerun because the session is re-initialized.
+  2. Restart the GitHub Actions runner service on the Windows host between runs:
+       Restart-Service -Name "actions.runner.*"
+     (replace wildcard with the actual runner service name from services.msc)
+
+  Permanent mitigation:
+  3. Upgrade the runner to the latest version (v2.334.0+) which includes session
+     management improvements. Check https://github.com/actions/runner/releases for
+     the latest stable version.
+  4. Disable auto-update and pin to a known-good runner version by setting
+     `RUNNER_ALLOW_RUNASROOT=false` and specifying the version in your runner
+     configuration script.
+  5. If operating ARC (Actions Runner Controller), upgrade the controller to use a
+     runner image version 2.334.0+ to pick up the fix.
+fix_code:
+  - language: yaml
+    label: 'Workflow with restart-runner step for self-hosted Windows runners (workaround)'
+    code: |
+      # Workaround: add a pre-step that verifies the runner session is healthy.
+      # This forces a new session token for each major step block.
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - name: Verify runner session (workaround for runner#3609)
+              run: Write-Host "Runner session active — version $env:RUNNER_VERSION"
+              shell: pwsh
+
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: dotnet build
+              shell: pwsh
+  - language: yaml
+    label: 'Script to upgrade self-hosted runner to latest version on Windows'
+    code: |
+      # Run on each Windows runner host to upgrade to the latest runner version.
+      # Execute from PowerShell as Administrator.
+
+      # Stop the runner service
+      Stop-Service -Name "actions.runner.*" -Force
+
+      # Download and replace the runner binary
+      $version = (Invoke-RestMethod "https://api.github.com/repos/actions/runner/releases/latest").tag_name.TrimStart('v')
+      Invoke-WebRequest "https://github.com/actions/runner/releases/download/v$version/actions-runner-win-x64-$version.zip" -OutFile runner.zip
+      Expand-Archive runner.zip -DestinationPath . -Force
+
+      # Restart the service
+      Start-Service -Name "actions.runner.*"
+      Write-Host "Runner upgraded to v$version"
+prevention:
+  - 'Keep self-hosted runners updated to the latest runner version — regression fixes are frequent'
+  - 'Monitor runner logs at _diag/Runner_*.log for session/message-queue errors between steps'
+  - 'Set up automatic runner version checks in your infrastructure pipeline'
+  - 'For critical pipelines, disable auto-update and pin to a tested runner version then upgrade on schedule'
+  - 'On Windows hosts, ensure the runner service account has rights to re-establish named pipe connections between steps'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3609'
+    label: 'actions/runner#3609: Self-hosted runner stuck "Waiting for runner" in multi-step jobs (90 reactions, open Dec 2024)'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'GitHub Actions Runner releases — check for v2.321.0 regression fixes'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'GitHub Docs: About self-hosted runners'

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

@@ -0,0 +1,88 @@
+id: runner-environment-185
+title: "Node.js 18 Removed from Toolcache After EOL — setup-node Falls Back to Slow Download or Times Out"
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node18
+  - toolcache
+  - eol
+  - setup-node
+  - runner-images
+patterns:
+  - regex: "Unable to find Node version '18|Couldn't find a version that satisfied.*18"
+    flags: i
+  - regex: 'Acquiring 18\.[0-9]+\.[0-9]+ - (x64|arm64) from.*node-versions'
+    flags: i
+  - regex: 'Client network socket disconnected before secure TLS connection was established'
+    flags: i
+  - regex: 'Request timeout.*node.*18|Error.*node.*18.*download'
+    flags: i
+error_messages:
+  - "Unable to find Node version '18' in the local cache."
+  - "Couldn't resolve the package 'node' to a version matching '18'"
+  - "Acquiring 18.20.4 - x64 from https://github.com/actions/node-versions/releases/download/18.20.4-xxxxxxxxxxxxxxxx/node-18.20.4-linux-x64.tar.gz"
+  - "Request timeout..."
+  - "Client network socket disconnected before secure TLS connection was established"
+root_cause: |
+  Node.js 18 reached end-of-life on **April 30, 2025**. GitHub subsequently removed it from the
+  pre-installed toolcache on all GitHub-hosted runner images (Ubuntu, macOS, and Windows). When
+  a workflow specifies `node-version: '18'` or `node-version: '18.x'`, the `actions/setup-node`
+  action cannot find Node 18 in the local toolcache and falls back to downloading the binary from
+  GitHub's node-versions release page. This remote download frequently times out on hosted runners
+  (the GitHub Releases endpoint for old Node versions is rate-limited under load), causing the step
+  to fail part-way through setup. On self-hosted runners without unrestricted outbound internet
+  access, the fallback download fails immediately with a TLS or connection error. The failure is
+  unexpected for teams that previously never pinned a `setup-node` step because Node 18 "just
+  worked" from the toolcache — after the removal, those workflows break silently on the next
+  runner image update. Distinct from `runner-environment-029` (Node.js 20 toolcache removal)
+  and `runner-environment-062` (ubuntu-latest default changing from Node 20 to 22).
+fix: |
+  Upgrade to a currently-supported Node.js LTS version. Node.js 22 is the current Active LTS
+  (supported until April 2027). Update the `node-version` field in your `setup-node` step and
+  verify your `package.json` `engines` field matches the new version:
+fix_code:
+  - language: yaml
+    label: "Upgrade to Node.js 22 (Active LTS)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+  - language: yaml
+    label: "Pin to .nvmrc / .node-version file for consistency"
+    code: |
+      # .nvmrc or .node-version in repo root:
+      # 22
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: "Matrix test across supported LTS versions"
+    code: |
+      strategy:
+        matrix:
+          node-version: ['20', '22']
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: ${{ matrix.node-version }}
+prevention:
+  - "Subscribe to Node.js EOL announcements at https://nodejs.org/en/about/previous-releases to know when to migrate"
+  - "Use `node-version-file: '.nvmrc'` so your CI and local environments stay in sync automatically"
+  - "Enable Dependabot or Renovate to auto-bump `node-version` in workflow files when LTS versions rotate"
+  - "Prefer `lts/*` for non-version-sensitive workflows to always track the current LTS without manual updates"
+  - "Avoid relying on the toolcache for EOL versions — always add an explicit `setup-node` step"
+docs:
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node"
+  - url: "https://nodejs.org/en/about/previous-releases"
+    label: "Node.js Release Schedule and EOL Dates"
+  - url: "https://github.com/actions/setup-node/issues/933"
+    label: "setup-node #933: Node 18 toolcache download timeout reports"
+  - url: "https://github.com/actions/runner-images"
+    label: "actions/runner-images — pre-installed toolcache contents"

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

@@ -0,0 +1,95 @@
+id: runner-environment-186
+title: "windows-2025 Runner Label Unexpectedly Includes VS 2026 — Pinned VS 2022 Paths Break"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-2025
+  - visual-studio
+  - runner-image
+  - msbuild
+  - cmake
+  - breaking-change
+patterns:
+  - regex: 'Cannot find path.*Visual Studio\\2022.*because it does not exist'
+    flags: i
+  - regex: 'Visual Studio 2022.*not found|MSBuild.*17\.[0-9]+.*not available'
+    flags: i
+  - regex: 'CMake.*generator.*Visual Studio 17 2022.*not available'
+    flags: i
+  - regex: 'vswhere.*version.*\[17,18\).*returned empty|No valid VS instances found'
+    flags: i
+  - regex: 'MSB4019.*Microsoft\.CppBuild\.targets.*was not found'
+    flags: i
+error_messages:
+  - "Cannot find path 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\MSBuild\\Microsoft\\VC' because it does not exist."
+  - "MSB4019: The imported project 'Microsoft.CppBuild.targets' was not found. Confirm that the expression in the Import declaration is correct."
+  - "CMake Error: CMake was unable to find a build program corresponding to \"Visual Studio 17 2022\"."
+  - "The C++ toolchain version 14.30 targeting platform 'x64' is not installed. Install it from the VS Installer."
+root_cause: |
+  In early 2026, some builds of the `windows-2025` runner image label began shipping with
+  Visual Studio 2026 (Public Preview) as the primary Visual Studio installation, removing or
+  demoting VS 2022 components that had been present in earlier `windows-2025` builds. Developers
+  who had explicitly pinned `runs-on: windows-2025` (rather than `windows-latest`) to preserve
+  VS 2022 compatibility found their workflows unexpectedly broken, because hardcoded paths to
+  `C:\Program Files\Microsoft Visual Studio\2022\...` no longer existed, and CMake generators
+  targeting "Visual Studio 17 2022" could not locate a matching installation.
+
+  This is distinct from the intentional `windows-latest` → VS 2026 migration documented in
+  `runner-environment-020`. In that case, developers pinned to a versioned label specifically
+  to avoid the change — the versioned label was supposed to be stable. The regression occurred
+  because `windows-2025` image builds that included VS 2026 were briefly pushed to the label's
+  rotation before being identified and rolled back.
+
+  Source: actions/runner-images#13638, actions/runner-images#14004.
+fix: |
+  Pin to `windows-2022` to guarantee a VS 2022 toolchain for the foreseeable future. Use
+  `vswhere.exe` to discover Visual Studio components at runtime rather than hardcoding
+  installation paths, which protects against future image changes on any Windows label.
+fix_code:
+  - language: yaml
+    label: "Pin to windows-2022 for guaranteed VS 2022"
+    code: |
+      jobs:
+        build:
+          # Use windows-2022 instead of windows-2025 to guarantee VS 2022 toolchain
+          runs-on: windows-2022
+  - language: yaml
+    label: "Use vswhere to discover MSBuild path at runtime"
+    code: |
+      - name: Locate MSBuild via vswhere
+        id: msbuild
+        shell: pwsh
+        run: |
+          $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+          $msbuild = & $vswhere -latest -requires Microsoft.Component.MSBuild `
+            -find MSBuild\**\Bin\MSBuild.exe | Select-Object -First 1
+          if (-not $msbuild) { throw "MSBuild not found via vswhere" }
+          "path=$msbuild" | Out-File -Append $env:GITHUB_OUTPUT
+
+      - name: Build solution
+        shell: pwsh
+        run: |
+          & "${{ steps.msbuild.outputs.path }}" MySolution.sln /p:Configuration=Release /p:Platform=x64
+  - language: yaml
+    label: "Use CMake with dynamic VS version detection"
+    code: |
+      - name: Configure CMake
+        run: |
+          # Let CMake auto-detect the installed VS version instead of pinning generator
+          cmake -B build -DCMAKE_BUILD_TYPE=Release
+        # Avoid: cmake -G "Visual Studio 17 2022" which fails if VS 2022 is absent
+prevention:
+  - "Use `vswhere.exe` to locate Visual Studio and MSBuild components at runtime — never hardcode installation paths"
+  - "Subscribe to the actions/runner-images releases feed to get notified when versioned labels are updated"
+  - "Avoid CMake `-G \"Visual Studio 17 2022\"` in favor of `cmake -B build` with auto-detection when possible"
+  - "For CUDA or other toolchain integrations that require a specific VS version, test on a matrix of runner labels to catch regressions early"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13638"
+    label: "runner-images #13638: windows-2025 label includes VS2026 regression report"
+  - url: "https://github.com/actions/runner-images/issues/14004"
+    label: "runner-images #14004: VS 2022 paths missing on windows-2025"
+  - url: "https://github.com/microsoft/vswhere"
+    label: "vswhere — Visual Studio locator (Microsoft)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 Runner Image Readme"

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

@@ -0,0 +1,90 @@
+id: runner-environment-187
+title: "ubuntu-24.04 Runner Missing software-properties-common — add-apt-repository Not Found"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - ubuntu-24.04
+  - apt
+  - ppa
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'add-apt-repository.*not found|command not found.*add-apt-repository'
+    flags: i
+  - regex: '/bin/(sh|bash).*add-apt-repository.*not found'
+    flags: i
+  - regex: 'Unable to locate executable file: add-apt-repository'
+    flags: i
+  - regex: 'No such file or directory.*add-apt-repository'
+    flags: i
+error_messages:
+  - "/bin/sh: 1: add-apt-repository: not found"
+  - "bash: add-apt-repository: command not found"
+  - "Error: Unable to locate executable file: add-apt-repository"
+  - "/usr/bin/add-apt-repository: No such file or directory"
+root_cause: |
+  The `ubuntu-24.04` GitHub-hosted runner image does not pre-install `software-properties-common`,
+  the Debian/Ubuntu package that provides the `add-apt-repository` command. On `ubuntu-22.04`
+  runners, `software-properties-common` was included by default, so workflows that used
+  `add-apt-repository` to add third-party PPAs (e.g., `ppa:deadsnakes/ppa` for older Python
+  versions, `ppa:graphics-drivers/ppa` for NVIDIA drivers) worked without any explicit install
+  step. After migrating to `ubuntu-24.04` — either explicitly or when `ubuntu-latest` switched
+  from 22.04 to 24.04 in March 2025 — these workflows fail immediately with "command not found".
+
+  The failure message points at the `add-apt-repository` line, but the actual missing dependency
+  is the `software-properties-common` package. Other apt commands in the same step (like
+  `apt-get update`) succeed, making the root cause less obvious.
+fix: |
+  Install `software-properties-common` before calling `add-apt-repository`. For new workflows,
+  prefer adding apt source lists directly using a signing key, which does not require
+  `software-properties-common` and is more reproducible.
+fix_code:
+  - language: yaml
+    label: "Install software-properties-common before using add-apt-repository"
+    code: |
+      - name: Add PPA and install package
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y software-properties-common
+          sudo add-apt-repository -y ppa:deadsnakes/ppa
+          sudo apt-get update
+          sudo apt-get install -y python3.11 python3.11-venv
+  - language: yaml
+    label: "Preferred: add repository via source list (no software-properties-common needed)"
+    code: |
+      - name: Add repository via signed source list
+        run: |
+          # Download and install the repository GPG key
+          curl -fsSL https://example.com/gpg.key \
+            | sudo gpg --dearmor -o /usr/share/keyrings/example-archive-keyring.gpg
+
+          # Add the apt source list with the key reference
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/example-archive-keyring.gpg] \
+            https://example.com/apt stable main" \
+            | sudo tee /etc/apt/sources.list.d/example.list > /dev/null
+
+          sudo apt-get update
+          sudo apt-get install -y example-package
+  - language: yaml
+    label: "Conditionally install software-properties-common (ubuntu-24.04 only)"
+    code: |
+      - name: Install apt prerequisites
+        run: |
+          # software-properties-common is not pre-installed on ubuntu-24.04
+          sudo apt-get install -y software-properties-common
+prevention:
+  - "Do not rely on `software-properties-common` being pre-installed — always add it as an explicit apt-get install step"
+  - "Prefer direct apt source list additions (with GPG key dearmoring) over PPAs for better reproducibility on ubuntu-24.04"
+  - "Verify pre-installed packages when migrating runner labels — check https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+  - "Test workflows explicitly on ubuntu-24.04 before relying on ubuntu-latest defaulting to 24.04"
+  - "Use `apt-get install -y --no-install-recommends` to keep explicit and minimal dependencies"
+docs:
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "Ubuntu 24.04 Runner Image Readme — pre-installed packages list"
+  - url: "https://github.com/actions/runner-images/issues/9848"
+    label: "runner-images #9848: ubuntu-latest migration to ubuntu-24.04 tracking issue"
+  - url: "https://manpages.ubuntu.com/manpages/noble/man1/add-apt-repository.1.html"
+    label: "add-apt-repository man page (Ubuntu Noble)"
+  - url: "https://help.launchpad.net/Packaging/PPA/InstallingSoftware"
+    label: "Launchpad PPA Installation Guide"

package/errors/runner-environment/setup-java-sudo-strips-java-home-env-reset.yml

@@ -0,0 +1,111 @@
+id: runner-environment-183
+title: "setup-java JAVA_HOME stripped by sudo env_reset on Ubuntu — wrong JDK used silently"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-java
+  - sudo
+  - java
+  - ubuntu
+  - env-reset
+  - sudoers
+  - java-home
+patterns:
+  - regex: 'error: invalid target release: \d+'
+    flags: 'i'
+  - regex: '(bad source file|class file has wrong version).*\d+\.\d+'
+    flags: 'i'
+error_messages:
+  - "error: invalid target release: 25"
+  - "error: invalid target release: 21"
+  - "error: invalid target release: 23"
+  - "class file has wrong version"
+root_cause: |
+  Ubuntu's sudoers policy includes `env_reset` and `secure_path` by default. When a
+  workflow step runs any command via `sudo` (e.g., `sudo apt-get install ...`,
+  `sudo ant build`, `sudo mvn package`), the environment is completely reset: PATH
+  reverts to the sudoers secure_path and JAVA_HOME is cleared.
+
+  Because the runner image has JDK 17 registered as the system default via
+  `update-alternatives`, any subsequent Java invocation under sudo — including
+  tool-wrapped invocations via Debian-packaged `ant` (which uses `java-wrappers.sh`
+  to detect Java through system alternatives) — silently uses JDK 17 regardless of
+  what `actions/setup-java` configured.
+
+  This causes silent failures when the build silently compiles against JDK 17 and
+  produces wrong artifacts, and explicit errors when the requested JDK is newer
+  than 17 and javac refuses with "error: invalid target release: N".
+
+  The root cause is not a bug in setup-java — it correctly sets JAVA_HOME and PATH
+  via $GITHUB_ENV / $GITHUB_PATH, which only apply to non-sudo process contexts.
+  Ubuntu's sudoers env_reset is OS-level behaviour that strips those env variables.
+fix: |
+  1. Pass JAVACMD explicitly to sudo: `sudo JAVACMD=$JAVA_HOME/bin/java ant ...`
+     (Debian-packaged ant reads JAVACMD before system alternatives)
+  2. Register the setup-java JDK as the system default before any sudo steps:
+     sudo update-alternatives --install /usr/bin/java java "$JAVA_HOME/bin/java" 2000
+     sudo update-alternatives --set java "$JAVA_HOME/bin/java"
+  3. Avoid running Java build tools via sudo entirely — install build dependencies
+     first, then run the build as the runner user (without sudo).
+  4. Use `sudo -E` to preserve the current environment (requires sudoers NOPASSWD
+     with env_keep or SETENV; not available by default on GitHub-hosted runners).
+fix_code:
+  - language: yaml
+    label: "Workaround: pass JAVACMD explicitly to sudo ant/maven"
+    code: |
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      # Debian ant uses java-wrappers which ignores JAVA_HOME — pass JAVACMD directly
+      - name: Build with ant (sudo)
+        run: sudo JAVACMD=$JAVA_HOME/bin/java ant build
+
+  - language: yaml
+    label: "Workaround: register JDK as system default before sudo steps"
+    code: |
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      - name: Register JDK as system default (for sudo)
+        run: |
+          sudo update-alternatives --install /usr/bin/java java "$JAVA_HOME/bin/java" 2000
+          sudo update-alternatives --set java "$JAVA_HOME/bin/java"
+          sudo update-alternatives --install /usr/bin/javac javac "$JAVA_HOME/bin/javac" 2000
+          sudo update-alternatives --set javac "$JAVA_HOME/bin/javac"
+
+      - name: Build (sudo now uses correct JDK)
+        run: sudo ant build
+
+  - language: yaml
+    label: "Best practice: separate install from build to avoid sudo"
+    code: |
+      - name: Install build dependencies
+        run: sudo apt-get install -y build-essential
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      # No sudo here — JAVA_HOME is intact
+      - name: Build
+        run: ant build
+prevention:
+  - "Avoid running Java build tools (ant, mvn, gradle) via sudo — install OS dependencies before setup-java, build without sudo"
+  - "After setup-java, verify sudo sees the correct JDK: sudo java -version"
+  - "For Debian-packaged tools (apt install ant), always pass JAVACMD=$JAVA_HOME/bin/java when invoking via sudo"
+  - "If sudo is unavoidable, register the JDK via update-alternatives immediately after setup-java"
+docs:
+  - url: "https://github.com/actions/setup-java/issues/997"
+    label: "ubuntu-latest uses wrong JDK version under sudo (setup-java#997)"
+  - url: "https://github.com/actions/setup-java/pull/1013"
+    label: "Update README for Ubuntu sudo JAVA_HOME behavior (setup-java PR#1013)"
+  - url: "https://manpages.ubuntu.com/manpages/noble/en/man5/sudoers.5.html"
+    label: "sudoers(5) — env_reset and secure_path"

package/errors/runner-environment/setup-python-free-threaded-arm64-broken-symlink.yml

@@ -0,0 +1,98 @@
+id: runner-environment-184
+title: "setup-python free-threaded Python (3.13t/3.14t) on windows-11-arm64 installs broken 0-byte python.exe symlink"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - free-threaded
+  - python
+  - windows-11-arm64
+  - symlink
+  - arm64
+  - reparse-point
+patterns:
+  - regex: 'Fatal Python error: Failed to import encodings module'
+    flags: 'i'
+  - regex: 'ModuleNotFoundError: No module named .encodings.'
+    flags: 'i'
+  - regex: 'Remove-Item.*python\.exe.*does not exist'
+    flags: 'i'
+error_messages:
+  - "Fatal Python error: Failed to import encodings module"
+  - "ModuleNotFoundError: No module named 'encodings'"
+  - "Remove-Item : Cannot find path '...\\arm64-freethreaded\\python.exe' because it does not exist."
+  - "Error happened during pip installation / upgrade"
+root_cause: |
+  The `win32-arm64-freethreaded` distribution zip for Python 3.13t and 3.14t packages
+  `python.exe` and `python3.exe` as Windows reparse points (symlinks) pointing to
+  `python3.13t.exe` / `python3.14t.exe`.
+
+  When actions/setup-python extracts and copies the zip contents to the tool cache on
+  `windows-11-arm64`, the symlink target is not found at the expected relative path —
+  the copy operation leaves a dangling 0-byte reparse point (`-a---l 0 python.exe`)
+  instead of a real executable.
+
+  `setup.ps1:131` then fails to Remove-Item the dangling reparse point (PowerShell
+  cannot delete it because the path resolves as non-existent), and the tool cache
+  entry has no working Python interpreter. When the action invokes the installed
+  python, it immediately crashes with "Fatal Python error: Failed to import encodings
+  module" because the 0-byte stub cannot locate its stdlib.
+
+  Non-free-threaded arm64 builds (3.11, 3.12, 3.13, 3.14) are not affected — only
+  the `*t` (free-threaded / GIL-free) variants hit this issue on windows-11-arm64.
+fix: |
+  1. Workaround: Use the non-free-threaded variant (3.13 instead of 3.13t) unless
+     the GIL-free runtime is explicitly required.
+  2. Workaround for arm64 only: Install free-threaded Python from NuGet, which
+     ships real executables instead of symlinks. Gate on runner.arch == 'ARM64'.
+  3. Wait for actions/setup-python to land a fix that correctly resolves Windows
+     reparse points in free-threaded zip distributions (tracked in setup-python#1307).
+fix_code:
+  - language: yaml
+    label: "Workaround: use non-free-threaded Python on windows-11-arm64"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          # Avoid '3.13t' / '3.14t' on windows-11-arm64 — use standard variant
+          python-version: '3.13'
+
+  - language: yaml
+    label: "Workaround: install free-threaded Python via NuGet on ARM64"
+    code: |
+      - name: Setup Python (non-ARM64)
+        if: runner.arch != 'ARM64'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13t'
+
+      - name: Install free-threaded Python via NuGet (windows-11-arm64 workaround)
+        if: runner.os == 'Windows' && runner.arch == 'ARM64'
+        run: |
+          nuget install python -Version 3.13.3t -OutputDirectory "$env:RUNNER_TEMP\nuget" -NonInteractive
+          $pythonDir = Get-ChildItem "$env:RUNNER_TEMP\nuget" -Filter "python.3*" | Select-Object -First 1
+          Add-Content $env:GITHUB_PATH "$($pythonDir.FullName)\tools"
+          Add-Content $env:GITHUB_PATH "$($pythonDir.FullName)\tools\Scripts"
+
+  - language: yaml
+    label: "Verification step: confirm Python works after setup"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13t'
+
+      - name: Verify Python installation
+        run: |
+          python --version
+          python -c "import sys; print(sys.version, sys._is_gil_enabled())"
+prevention:
+  - "Do not use free-threaded Python variants (3.13t, 3.14t) on windows-11-arm64 until setup-python#1307 is resolved"
+  - "Gate free-threaded Python tests: run on ubuntu-latest or windows-latest (x64), avoid windows-11-arm64 for *t variants"
+  - "Add a verification step (python -c 'import sys') after setup-python to catch broken installs before test steps"
+  - "Follow setup-python#1307 for the official fix — upgrade as soon as a patched version is released"
+docs:
+  - url: "https://github.com/actions/setup-python/issues/1307"
+    label: "setup-python fails for free-threaded Python (3.13t/3.14t) on windows-11-arm64 (setup-python#1307)"
+  - url: "https://github.com/onnx/onnx/pull/7869"
+    label: "Install free-threaded Python from NuGet on windows-11-arm (workaround reference)"
+  - url: "https://docs.python.org/3.13/whatsnew/3.13.html#free-threaded-cpython"
+    label: "Python 3.13 — Free-threaded CPython documentation"