@htekdev/actions-debugger 1.0.110 → 1.0.112

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

@@ -0,0 +1,132 @@
+id: runner-environment-180
+title: 'ubuntu-24.04 removes Mono/MSBuild/NuGet — .NET Framework net48/net40 builds fail with "command not found"'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - ubuntu-latest
+  - mono
+  - msbuild
+  - nuget
+  - dotnet-framework
+  - migration
+  - tool-removed
+patterns:
+  - regex: 'mono: command not found'
+    flags: 'i'
+  - regex: 'msbuild: command not found'
+    flags: 'i'
+  - regex: '/usr/bin/msbuild.*No such file or directory'
+    flags: 'i'
+  - regex: 'nuget: command not found'
+    flags: 'i'
+  - regex: 'Could not find file.*msbuild\.exe'
+    flags: 'i'
+error_messages:
+  - "mono: command not found"
+  - "msbuild: command not found"
+  - "nuget: command not found"
+  - "/usr/bin/msbuild: No such file or directory"
+  - "bash: line 1: mono: command not found"
+root_cause: |
+  When GitHub Actions migrated `ubuntu-latest` to Ubuntu 24.04 (rollout Dec 2024 –
+  Jan 2025, runner-images#10636), the Mono framework, mono-based MSBuild, and mono-based
+  NuGet were intentionally removed from the Ubuntu 24.04 runner image. These packages
+  are not available in Ubuntu 24.04 (Noble Numbat) apt repositories because Mono is not
+  maintained for Noble.
+
+  Affected workflows:
+  - .NET Framework projects targeting net40, net45, net46, net47, net48 built on Linux
+    using Mono (common for Unity CI, Windows-targeted libraries, legacy C# projects)
+  - Any workflow running `mono`, `msbuild`, or `nuget` shell commands on ubuntu-latest
+  - Third-party actions that internally call mono (e.g., Unity build actions, some .NET
+    test runners)
+
+  The failure is immediate and obvious ("command not found") but the root cause is often
+  unclear because the workflow worked fine on ubuntu-22.04. The ubuntu-latest label
+  silently changed the underlying image, not the workflow YAML.
+
+  Source: actions/runner-images#10636 (384 reactions, closed Jan 2025),
+  actions/runner-images#11675 (mono specifically, closed "not planned" — Mono will NOT
+  be added back to ubuntu-24.04).
+fix: |
+  Option 1 (recommended for most cases): Switch to windows-latest
+  .NET Framework targets are first-class on Windows runners which still include MSBuild,
+  NuGet, and full .NET Framework support. Most .csproj net48 builds run correctly on
+  windows-latest.
+
+  Option 2: Install Mono at runtime on Ubuntu 22.04 (not 24.04)
+  Pin to ubuntu-22.04 (supported until April 2027) and install Mono via apt at runtime:
+    sudo apt-get install -y mono-complete msbuild
+
+  Option 3: Migrate to .NET Core / .NET 6+ with multi-targeting
+  Add a `net8.0` target to your csproj alongside `net48` for CI builds on Linux, and
+  build the Linux target on ubuntu-latest. The Windows-only target can be built on
+  windows-latest in a separate matrix job.
+
+  Option 4: Use a Docker container with Mono
+  Run the build step in a `mono:latest` container:
+    container: mono:latest
+fix_code:
+  - language: yaml
+    label: 'Switch net48 / Mono builds to windows-latest'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest   # .NET Framework is fully supported on Windows runners
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+            - name: Restore NuGet packages
+              run: nuget restore MySolution.sln
+            - name: Build
+              run: msbuild MySolution.sln /p:Configuration=Release
+  - language: yaml
+    label: 'Pin to ubuntu-22.04 and install Mono at runtime'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04   # ubuntu-24.04 has no Mono; 22.04 supported until April 2027
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install Mono
+              run: |
+                sudo apt-get update -q
+                sudo apt-get install -y mono-complete msbuild
+            - name: Build
+              run: msbuild MySolution.sln /p:Configuration=Release
+  - language: yaml
+    label: 'Matrix build separating Linux .NET Core from Windows .NET Framework'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  target: net8.0
+                - os: windows-latest
+                  target: net48
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: microsoft/setup-msbuild@v2
+              if: runner.os == 'Windows'
+            - name: Build
+              run: dotnet build -f ${{ matrix.target }} -c Release
+prevention:
+  - 'Pin `runs-on: ubuntu-22.04` for any workflow requiring Mono, msbuild, or nuget CLI on Linux'
+  - 'Use `windows-latest` for all .NET Framework (net40/45/46/47/48) builds — MSBuild is native there'
+  - 'Audit workflows for bare `mono`, `msbuild`, or `nuget` commands before migrating ubuntu-latest'
+  - 'Consider migrating legacy .NET Framework projects to .NET 8+ for platform-agnostic CI'
+  - 'Check runner software lists at https://github.com/actions/runner-images for tool availability per OS'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/10636'
+    label: 'actions/runner-images#10636: Ubuntu-latest migrates to Ubuntu-24.04 (384 reactions, Jan 2025)'
+  - url: 'https://github.com/actions/runner-images/issues/11675'
+    label: 'actions/runner-images#11675: Mono missing on Ubuntu 24.04 (closed not_planned — will not be added back)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'Ubuntu 24.04 runner image software list'
+  - url: 'https://github.com/microsoft/setup-msbuild'
+    label: 'microsoft/setup-msbuild action for Windows runners'

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-registration-token-502-burst.yml

@@ -0,0 +1,102 @@
+id: runner-environment-179
+title: 'Runner Registration Token Endpoint Returns 502 Under Concurrent Spawn Bursts'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - ephemeral
+  - registration
+  - autoscaler
+  - burst
+  - 502
+patterns:
+  - regex: 'HTTP Error 502: Bad Gateway'
+    flags: 'i'
+  - regex: 'registration-token.*502|502.*Bad Gateway.*registration'
+    flags: 'i'
+  - regex: 'HTTPError.*502|urlopen error.*502'
+    flags: 'i'
+error_messages:
+  - 'HTTP Error 502: Bad Gateway'
+  - 'urllib.error.HTTPError: HTTP Error 502: Bad Gateway'
+  - 'POST https://api.github.com/repos/{owner}/{repo}/actions/runners/registration-token — 502'
+root_cause: |
+  GitHub REST endpoint:
+    POST https://api.github.com/repos/{owner}/{repo}/actions/runners/registration-token
+
+  returns HTTP 502 Bad Gateway under burst load when many ephemeral runners attempt to
+  register concurrently (e.g., triggered by webhook-driven autoscalers on workflow_job.queued
+  events). The burst saturates the GitHub backend's registration token issuer.
+
+  The reference runner setup scripts (run.sh / config.sh flow) do NOT retry 5xx responses —
+  a single transient 502 causes the container to exit immediately before registration completes.
+  For ephemeral autoscaler setups (Modal, Lambda, Kubernetes pod-per-job), the container slot
+  is burned and no runner is available for the queued job.
+
+  Phantom containers accumulate: the autoscaler billed for the container, GitHub never received
+  a registration, and the autoscaler's max_containers cap can be held by dead slots — stalling
+  the merge queue for hours.
+
+  Source: actions/runner#4399 (May 2026, open issue, observed during 20+ concurrent registrations
+  — ~21 phantom containers during a webhook-driven burst at ~16:00-17:00 UTC on 2026-05-04).
+fix: |
+  1. Add exponential backoff to your registration token call (4 attempts, 2^n second delays).
+  2. Stagger autoscaler spawns with per-container random jitter (0-10 seconds) to break up
+     concurrent registration bursts before they hit the endpoint simultaneously.
+  3. Switch to JIT runner tokens — they are pre-assigned per job and do not require a burst-
+     sensitive registration token call:
+       POST /repos/{owner}/{repo}/actions/runners/generate-jitconfig
+  4. Reduce max_concurrent_spawns in your autoscaler to limit peak registration load.
+  5. Implement phantom container detection: health-check containers shortly after spawn and
+     kill any that failed to register within N seconds.
+fix_code:
+  - language: yaml
+    label: 'Python — retry-with-backoff on 502 when minting registration token'
+    code: |
+      import time, json, urllib.request, urllib.error
+
+      def mint_registration_token(owner, repo, github_token):
+          url = f"https://api.github.com/repos/{owner}/{repo}/actions/runners/registration-token"
+          headers = {
+              "Authorization": f"token {github_token}",
+              "Accept": "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+          }
+          for attempt in range(4):
+              try:
+                  req = urllib.request.Request(url, method="POST", headers=headers)
+                  with urllib.request.urlopen(req, timeout=15) as resp:
+                      return json.load(resp)["token"]
+              except urllib.error.HTTPError as e:
+                  if 500 <= e.code < 600 and attempt < 3:
+                      delay = 2 ** attempt  # 1s, 2s, 4s
+                      print(f"Registration token {e.code}, retrying in {delay}s (attempt {attempt+1}/4)...")
+                      time.sleep(delay)
+                      continue
+                  raise
+  - language: yaml
+    label: 'Autoscaler — add random jitter per container spawn to break up burst'
+    code: |
+      import asyncio, random
+
+      async def handle_workflow_job_queued(event):
+          # Stagger spawns: random delay 0-10s reduces simultaneous token requests
+          jitter = random.uniform(0, 10)
+          await asyncio.sleep(jitter)
+          token = await mint_registration_token(owner, repo, github_token)
+          await spawn_ephemeral_container(token)
+prevention:
+  - 'Add exponential backoff (4 attempts, 2^n seconds) for 5xx responses in all registration token calls.'
+  - 'Add random per-container spawn jitter (0-10s) in your autoscaler to break up concurrent registration bursts.'
+  - 'Switch to JIT runner tokens (generate-jitconfig) for burst autoscaler workloads — they do not hit the burst-sensitive registration endpoint.'
+  - 'Monitor for phantom containers: any container that does not show as registered within 60 seconds of spawn should be terminated.'
+  - 'Cap max_concurrent_spawns conservatively (≤10) and tune based on observed 502 rates.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4399'
+    label: 'actions/runner#4399: Registration token endpoint returns 502 in bursts (May 2026)'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners#create-a-registration-token-for-a-repository'
+    label: 'GitHub REST API: Create a registration token for a repository'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners#create-configuration-for-a-just-in-time-runner-for-a-repository'
+    label: 'GitHub REST API: Create JIT runner config (avoids burst-sensitive registration token)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'

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"