@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/runner-environment/setup-node-yarn-not-installed-self-hosted.yml

@@ -0,0 +1,76 @@
+id: runner-environment-074
+title: "setup-node Does Not Install Yarn on Self-Hosted Runners"
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - yarn
+  - self-hosted-runner
+  - package-manager
+  - corepack
+patterns:
+  - regex: "yarn.*command not found|command not found.*yarn"
+    flags: "i"
+  - regex: "yarn: not found|sh.*yarn.*127"
+    flags: "i"
+error_messages:
+  - "yarn: command not found"
+  - "/bin/sh: 1: yarn: not found"
+  - "Process completed with exit code 127"
+root_cause: |
+  `actions/setup-node` does NOT install Yarn on self-hosted runners. On GitHub-hosted runners,
+  Yarn is pre-installed as part of the runner image (included in ubuntu-22.04, ubuntu-24.04,
+  macOS, and Windows hosted images). When migrating to self-hosted runners, workflows that call
+  `yarn install` fail with `yarn: command not found` (exit code 127) because the binary is absent.
+
+  The action provides `cache: 'yarn'` to restore cached modules and registry URL configuration,
+  but does NOT bootstrap the Yarn binary itself. As of Node.js 16+, Yarn v2+ (Berry) is distributed
+  via Corepack, but Corepack shims are disabled by default in Node.js — setup-node@v4 requires
+  explicit `enable-corepack: true` to activate them.
+
+  159 reactions on actions/setup-node#182 (open since Dec 2021).
+fix: |
+  Option A (Yarn v1): Install Yarn explicitly via npm in a dedicated step before using it.
+  Option B (Yarn v2/v3/v4 Berry): Enable Corepack via setup-node's `enable-corepack: true`
+  input together with a `packageManager` field in package.json specifying the exact Yarn version.
+  Option C: Use `volta-cli/action` or a custom self-hosted runner image with Yarn pre-installed.
+fix_code:
+  - language: yaml
+    label: "Option A: install Yarn v1 explicitly (compatible with all self-hosted runners)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            cache: 'yarn'
+        - name: Install Yarn
+          run: npm install -g yarn@1
+        - name: Install dependencies
+          run: yarn install --frozen-lockfile
+
+  - language: yaml
+    label: "Option B: enable Corepack for Yarn v2+ (requires packageManager in package.json)"
+    code: |
+      # Requires package.json to include: "packageManager": "yarn@4.x.x"
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            enable-corepack: true   # activates Corepack shims including the yarn binary
+            cache: 'yarn'
+        - name: Install dependencies
+          run: yarn install --immutable
+prevention:
+  - "On self-hosted runners, never assume GitHub-hosted image tools are pre-installed — audit all tool dependencies."
+  - "Explicitly install or activate package managers (yarn, pnpm, bun) in workflow setup steps."
+  - "Use enable-corepack: true in setup-node@v4 for Yarn v2+ projects with packageManager in package.json."
+  - "Consider maintaining a custom self-hosted runner image with required package managers pre-installed."
+docs:
+  - url: "https://github.com/actions/setup-node/issues/182"
+    label: "actions/setup-node #182 — Yarn not installed on self-hosted runners (159 reactions)"
+  - url: "https://github.com/actions/setup-node#corepack"
+    label: "setup-node — Corepack support documentation"
+  - url: "https://yarnpkg.com/corepack"
+    label: "Yarn — Corepack installation guide"

package/errors/runner-environment/setup-python-externally-managed-env-error.yml

@@ -0,0 +1,95 @@
+id: "runner-environment-073"
+title: "pip install fails with externally-managed-environment on Ubuntu 22.04/24.04"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "python"
+  - "pip"
+  - "ubuntu-2204"
+  - "ubuntu-2404"
+  - "pep668"
+  - "virtualenv"
+patterns:
+  - regex: "error: externally-managed-environment"
+    flags: "i"
+  - regex: "This environment is externally managed"
+    flags: "i"
+  - regex: "To install Python packages system-wide, try apt-get install"
+    flags: "i"
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "╰─> To install Python packages system-wide, try apt-get install python3-xyz"
+  - "hint: See PEP 668 for the detailed specification of this behavior."
+root_cause: |
+  PEP 668 (adopted in Python 3.11) marks system-managed Python installations as
+  "externally managed" to prevent pip from overwriting OS package manager state.
+  Ubuntu 22.04 and 24.04 runner images ship with a system Python 3.10/3.12 that
+  carries this marker, and newer versions of pip (>=22.3) enforce it.
+
+  Workflows that run bare `pip install` or `pip install -r requirements.txt` against
+  the system interpreter fail with this error. The issue did not exist on ubuntu-20.04
+  (Python 3.8) and began appearing when teams migrated to ubuntu-22.04 or ubuntu-latest
+  (which moved to ubuntu-24.04 in May 2025).
+
+  Even when setup-python is used, if the step that runs pip install activates the wrong
+  interpreter (e.g., the system Python instead of the toolcache one), the same error
+  occurs. This often happens when shell scripts or Makefiles call `python3` directly.
+fix: |
+  Option 1 (preferred): Use a virtual environment so pip installs into an isolated,
+  non-system directory that is not subject to the externally-managed restriction.
+
+  Option 2: Pin setup-python@v5 to your required version; its toolcache interpreter
+  is not marked as externally managed and accepts pip installs freely.
+
+  Option 3 (quick fix, not recommended for production): Pass --break-system-packages.
+fix_code:
+  - language: yaml
+    label: "Use a virtual environment (recommended)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Create virtualenv and install
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate  # Linux/macOS
+          # .venv\Scripts\activate   # Windows
+          pip install -r requirements.txt
+
+      - name: Run with virtualenv active
+        run: |
+          source .venv/bin/activate
+          pytest
+
+  - language: yaml
+    label: "Use setup-python toolcache interpreter (pip installs without restriction)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt   # uses toolcache Python, not system Python
+
+  - language: yaml
+    label: "Quick fix: --break-system-packages (not recommended)"
+    code: |
+      - name: Install dependencies
+        run: pip install --break-system-packages -r requirements.txt
+prevention:
+  - "Always activate setup-python before any pip install call to use the toolcache interpreter instead of system Python."
+  - "Use virtual environments in CI workflows, especially when migrating from ubuntu-20.04 to 22.04/24.04."
+  - "Audit Makefiles and shell scripts that call 'python3' directly — they may bypass setup-python's PATH manipulation."
+  - "Run your workflow on ubuntu-22.04 or ubuntu-24.04 in a test branch before migrating from ubuntu-20.04."
+docs:
+  - url: "https://peps.python.org/pep-0668/"
+    label: "PEP 668 — Marking Python base environments as externally managed"
+  - url: "https://github.com/actions/setup-python/issues/1280"
+    label: "actions/setup-python#1280 — externally-managed-environment discussion"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software"
+    label: "GitHub Docs — Supported software on GitHub-hosted runners"
+  - url: "https://github.com/actions/runner-images/issues/11101"
+    label: "runner-images#11101 — Ubuntu 20.04 retirement tracking issue"

package/errors/runner-environment/windows-2019-runner-retired-june2025.yml

@@ -0,0 +1,118 @@
+id: runner-environment-065
+title: "Windows 2019 Runner Retired — Jobs Fail After June 30, 2025"
+category: runner-environment
+severity: error
+tags:
+  - windows-2019
+  - runner-retirement
+  - deprecated
+  - windows
+  - runner-label
+  - brownout
+patterns:
+  - regex: "windows-2019.*no longer supported"
+    flags: "i"
+  - regex: "runs-on.*windows-2019.*deprecated"
+    flags: "i"
+  - regex: "The windows-2019 runner image is no longer supported"
+    flags: "i"
+  - regex: "Error.*windows-2019.*not available"
+    flags: "i"
+error_messages:
+  - "Error: The windows-2019 runner image is no longer supported. Migrate to windows-2022 or windows-2025."
+  - "##[error]Job failed: The runner image 'windows-2019' is deprecated and no longer supported."
+  - "Windows Server 2019 is no longer supported as a GitHub Actions runner image."
+root_cause: |
+  The `windows-2019` runner image was retired by GitHub Actions on June 30, 2025
+  (runner-images#12045). Deprecation brownouts began June 1, 2025, during which
+  jobs using `windows-2019` would temporarily fail during scheduled brownout
+  windows (June 3, 10, 17, 24 — 13:00–21:00 UTC). After June 30, 2025, the
+  image was fully unsupported and jobs using `runs-on: windows-2019` fail
+  immediately with no runner available.
+
+  Windows Server 2019 reached End of Mainstream Support from Microsoft on
+  January 9, 2024, making it untenable as a CI runner image for security
+  and support reasons.
+
+  Key differences that may require migration work:
+  - Windows 2022 and 2025 use Visual Studio 2022 and VS 2026 respectively
+    (windows-2019 had Visual Studio 2019). MSBuild project compatibility,
+    compiler toolset versions, and SDK paths differ.
+  - Some pre-installed tools (e.g., specific .NET Framework versions, MSVC
+    compiler toolsets, legacy SDK components) were present on windows-2019
+    but not on windows-2022 or windows-2025.
+  - Windows Server 2025 images include Windows PowerShell 5.1 and
+    PowerShell 7.x; path behaviors for Windows-specific paths may differ.
+fix: |
+  Migrate runs-on: windows-2019 to runs-on: windows-2022 or windows-2025:
+
+  1. **windows-2022** (recommended for most teams): Includes VS 2022,
+     .NET 6/7/8 LTS, and the same tool catalog as windows-2019 minus
+     legacy VS 2019 components. Most projects migrate with no changes.
+
+  2. **windows-2025** (latest, includes VS 2026): Best for projects
+     requiring the latest MSVC toolchain, Windows 11 APIs, or ARM64
+     development. Note that windows-latest now points to this image.
+
+  3. **Check MSBuild ToolsVersion**: If your project uses MSBuild with
+     explicit ToolsVersion="15.0" or "16.0" references, update to
+     ToolsVersion="Current" or leave it unspecified to use the
+     installed version.
+
+  4. **Verify .NET SDK availability**: Confirm the .NET SDK version your
+     project needs is available on the target image by checking the
+     published software inventory for windows-2022 or windows-2025.
+fix_code:
+  - language: yaml
+    label: "Migrate from windows-2019 to windows-2022"
+    code: |
+      jobs:
+        build:
+          # windows-2019 is RETIRED as of June 30, 2025
+          # runs-on: windows-2019  ← no longer supported
+          runs-on: windows-2022     # VS 2022, .NET 8 LTS pre-installed
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyProject.sln /p:Configuration=Release
+  - language: yaml
+    label: "Migrate to windows-2025 with VS 2026 (latest)"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2025    # Windows Server 2025, VS 2026
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup .NET
+              uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '8.x'
+            - name: Build
+              run: dotnet build --configuration Release
+  - language: yaml
+    label: "Matrix to test windows-2022 and windows-2025 before committing"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [windows-2022, windows-2025]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: msbuild MyProject.sln
+prevention:
+  - "Avoid pinning to specific OS-versioned runner labels (windows-2019, ubuntu-20.04) in long-lived workflows — add a review calendar reminder every 12 months to check for upcoming deprecations."
+  - "Subscribe to GitHub notifications for the actions/runner-images repository to receive deprecation announcements months before retirement."
+  - "Use `windows-latest` for flexibility where VS version compatibility isn't critical — it automatically tracks the current supported image."
+  - "After migrating, run the full test suite and check compiler/toolchain version outputs in CI to catch any implicit behavior differences."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12045"
+    label: "runner-images #12045: Windows 2019 deprecation announcement (June 2025)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md"
+    label: "Windows Server 2022 runner software inventory"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 runner software inventory"
+  - 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 — available images"

package/errors/runner-environment/windows-2022-docker-daemon-not-started.yml

@@ -0,0 +1,108 @@
+id: runner-environment-069
+title: "Windows 2022 Runner Docker Engine Named Pipe Not Found on Start"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - docker
+  - runner-image
+  - intermittent
+  - named-pipe
+patterns:
+  - regex: "failed to connect to the docker API at npipe:////\\.?/pipe/docker_engine"
+    flags: "i"
+  - regex: "open //\\.?/pipe/docker_engine.*The system cannot find the file specified"
+    flags: "i"
+  - regex: "error during connect.*pipe/docker_engine.*daemon running"
+    flags: "i"
+  - regex: "Docker Engine.*Stopped|docker.*service.*not running"
+    flags: "i"
+error_messages:
+  - "failed to connect to the docker API at npipe:////./pipe/docker_engine; check if the path is correct and if the daemon is running: open //./pipe/docker_engine: The system cannot find the file specified."
+  - "error during connect: Get \"http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.45/info\": open //./pipe/docker_engine: The system cannot find the file specified."
+root_cause: |
+  On GitHub-hosted `windows-2022` runners, the Docker Engine service occasionally
+  fails to start before the workflow job begins. The Docker Engine runs as a Windows
+  service (`docker`) and the runner sometimes starts executing job steps before the
+  service has fully initialized and opened its named pipe at `//./pipe/docker_engine`.
+
+  This is an intermittent race condition between the runner agent startup and the
+  Docker Engine service startup sequence. The issue was reported in February 2026
+  (runner-images#13729) and confirmed to affect `windows-2022` at ~50% frequency
+  for some users. The `windows-2025` image is less affected.
+
+  The Docker Engine service shows `Status: Stopped` when queried immediately after
+  the runner starts. Manually starting the service (via `Start-Service docker`)
+  resolves the issue for that run. Job reruns also frequently succeed because they
+  land on a fresh host with Docker already running.
+fix: |
+  Add a step early in your job to verify Docker is running and start it if not:
+
+  ```yaml
+  - name: Ensure Docker Engine is running
+    shell: pwsh
+    run: |
+      $service = Get-Service -Name docker -ErrorAction SilentlyContinue
+      if ($service.Status -ne 'Running') {
+        Start-Service docker
+        $timeout = 60
+        $elapsed = 0
+        while ((Get-Service docker).Status -ne 'Running' -and $elapsed -lt $timeout) {
+          Start-Sleep -Seconds 2
+          $elapsed += 2
+        }
+      }
+      docker info
+  ```
+
+  If the issue is sporadic, a simpler retry on job failure may suffice. You can
+  also switch to `windows-2025` which has a lower incidence of this race condition.
+fix_code:
+  - language: yaml
+    label: "Guard step — ensure Docker service is running before use"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Ensure Docker Engine is running
+              shell: pwsh
+              run: |
+                $svc = Get-Service docker -ErrorAction SilentlyContinue
+                if ($null -eq $svc -or $svc.Status -ne 'Running') {
+                  Write-Host "Docker service not running — starting..."
+                  Start-Service docker
+                  $deadline = (Get-Date).AddSeconds(60)
+                  while ((Get-Service docker).Status -ne 'Running') {
+                    if ((Get-Date) -gt $deadline) { throw "Docker failed to start in 60s" }
+                    Start-Sleep -Seconds 2
+                  }
+                  Write-Host "Docker service started."
+                }
+                docker info
+
+            - name: Build Docker image
+              run: docker build -t myimage .
+  - language: yaml
+    label: "Alternative — switch to windows-2025 (less affected)"
+    code: |
+      jobs:
+        build:
+          # windows-2025 has a lower frequency of this race condition
+          runs-on: windows-2025
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build Docker image
+              run: docker build -t myimage .
+prevention:
+  - "Add a Docker health-check step before any `docker` commands on Windows runners."
+  - "Consider using `windows-2025` which has fewer reports of this race condition."
+  - "Enable job reruns — this race condition is intermittent and reruns usually succeed."
+  - "Subscribe to runner-images announcements; GitHub is tracking this as a runner startup issue."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13729"
+    label: "GitHub Issue: windows-2022 docker not available when runner starts"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "About GitHub-hosted runners"

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

@@ -0,0 +1,96 @@
+id: silent-failures-031
+title: "cache-hit Output Is a String Not a Boolean — Bare true Comparison Always False"
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions/cache
+  - cache-hit
+  - string-comparison
+  - boolean-coercion
+  - conditional
+  - step-outputs
+patterns:
+  - regex: "cache-hit\\s*[!=]=\\s*true(?!')"
+    flags: "i"
+  - regex: "if:\\s+steps\\.\\w+\\.outputs\\.cache-hit\\s*$"
+    flags: "im"
+error_messages:
+  - "steps.cache.outputs.cache-hit == true"
+  - "steps.cache.outputs.cache-hit != true"
+root_cause: |
+  The `cache-hit` output from `actions/cache` and `actions/cache/restore` is a **string** value
+  (`'true'` or `'false'`), not a native boolean. GitHub Actions expression syntax uses strict
+  equality for `==` — there is no implicit type coercion between strings and booleans.
+
+  This means:
+  - `steps.cache.outputs.cache-hit == true`  → ALWAYS false  (string 'true' ≠ boolean true)
+  - `steps.cache.outputs.cache-hit != true`  → ALWAYS true   (install step always runs)
+  - `if: steps.cache.outputs.cache-hit`      → ALWAYS true   ('false' is a non-empty string)
+
+  The most destructive case: `if: steps.cache.outputs.cache-hit != true` is intended to
+  skip the install step on cache hit, but it always evaluates to `true` (runs every time),
+  so the install always runs even after a successful cache restore. Build times remain
+  unchanged, no error is shown, and the caching appears to be broken.
+
+  This applies to ALL GitHub Actions step outputs — they are always strings. A separate
+  but related issue is `cache-hit-restore-keys-misleading` (cache-hit is 'true' on partial
+  key match); this entry covers the unquoted boolean comparison pattern specifically.
+fix: |
+  Always compare `cache-hit` to the string `'true'` with single quotes:
+
+  - Skip install on cache hit:  `if: steps.cache.outputs.cache-hit != 'true'`
+  - Confirm cache was used:     `if: steps.cache.outputs.cache-hit == 'true'`
+
+  Do NOT use bare `true` / `false` (without quotes) in comparisons with step outputs.
+  Do NOT use `if: steps.cache.outputs.cache-hit` as a truthy check — the string 'false'
+  is truthy in most contexts and will always pass.
+fix_code:
+  - language: yaml
+    label: "Correct string comparison for cache-hit (single quotes required)"
+    code: |
+      - name: Cache node_modules
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      # ❌ WRONG: string 'true' != boolean true → always runs (never skips on cache hit)
+      - name: Install (broken — always runs)
+        if: steps.cache.outputs.cache-hit != true
+        run: npm ci
+
+      # ✅ CORRECT: compare to string 'true' with single quotes
+      - name: Install (correct — skips on cache hit)
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Full cache-then-install pattern with correct comparisons"
+    code: |
+      - uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Confirm cache was used
+        if: steps.npm-cache.outputs.cache-hit == 'true'
+        run: echo "Cache hit — install skipped"
+prevention:
+  - "Always compare step outputs to string literals with quotes: `== 'true'` not `== true`."
+  - "Remember: ALL GitHub Actions step outputs are strings — never native booleans or numbers."
+  - "Use `actionlint` to lint workflow YAML; it detects boolean vs string type mismatches in conditionals."
+  - "Verify caching is working by observing run time reduction — a successful cache hit noticeably speeds up installs."
+docs:
+  - url: "https://github.com/actions/cache#outputs"
+    label: "actions/cache README: outputs — cache-hit is a string"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#steps-context"
+    label: "GitHub Docs: steps context — all outputs are strings"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#operators"
+    label: "GitHub Docs: Expression operators — == uses strict equality"

package/errors/silent-failures/checkout-lfs-pointer-not-content.yml

@@ -0,0 +1,105 @@
+id: silent-failures-033
+title: "actions/checkout lfs: true Leaves LFS Pointer Metadata Instead of Actual File Content"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - git-lfs
+  - lfs
+  - pointer-file
+  - large-file-storage
+  - self-hosted
+patterns:
+  - regex: "version https://git-lfs\\.github\\.com/spec/v1"
+    flags: "i"
+  - regex: "oid\\s+sha256:[0-9a-f]{64}"
+    flags: "i"
+  - regex: "lfs:\\s*true"
+    flags: "i"
+error_messages:
+  - "version https://git-lfs.github.com/spec/v1"
+  - "oid sha256:f23e4c2b1244bc93085dbccf17c447e54..."
+  - "size 58951008"
+root_cause: |
+  When actions/checkout runs with lfs: true, it configures LFS credentials and
+  attempts to download actual file content for LFS-tracked files. However, the
+  step can exit 0 (success) while leaving LFS pointer metadata files on disk
+  instead of the actual binary or text content.
+
+  This happens silently in several situations:
+
+  - Self-hosted runners without git-lfs installed: the LFS fetch is skipped
+    because the binary is not present. No error is emitted.
+  - LFS bandwidth quota exhausted: GitHub's LFS bandwidth limit (1 GB/month
+    free tier) is silently hit; pointer files remain without a clear warning.
+  - Private cross-repo LFS: checking out a different repository with lfs: true
+    using a token may fail LFS authentication without surfacing an error.
+  - Fork pull requests: LFS objects contributed from fork branches may not be
+    accessible to the base repository workflow.
+
+  The result: downstream tools receive a text file starting with
+  "version https://git-lfs.github.com/spec/v1" instead of actual content,
+  causing opaque failures in build tools, image processors, or test suites.
+fix: |
+  Add an explicit LFS fetch step after checkout. On GitHub-hosted runners,
+  lfs: true is generally sufficient if LFS is configured on the repository.
+  For self-hosted runners, ensure git-lfs is installed before the checkout
+  step runs:
+  - Ubuntu/Debian: sudo apt-get install git-lfs
+  - macOS: brew install git-lfs
+  - Windows: winget install GitHub.GitLFS
+
+  After installation, run the LFS initialization command (git lfs install)
+  once per runner to configure the global LFS hooks.
+
+  To detect unfetched pointer files, add a validation step that checks for
+  the LFS pointer header string in files that should contain real content.
+fix_code:
+  - language: yaml
+    label: "Self-hosted runner — install git-lfs before checkout"
+    code: |
+      steps:
+        - name: Ensure git-lfs is installed
+          run: |
+            sudo apt-get update -qq
+            sudo apt-get install -y git-lfs
+          shell: bash
+
+        - uses: actions/checkout@v4
+          with:
+            lfs: true
+
+        - name: Verify LFS content downloaded
+          run: |
+            if grep -rl "version https://git-lfs.github.com/spec/v1" . \
+               --include="*.bin" --include="*.png" --include="*.zip" 2>/dev/null | head -1 | grep -q .; then
+              echo "ERROR: LFS pointer files found — actual content was not downloaded"
+              exit 1
+            fi
+            echo "LFS check passed — no pointer files found"
+          shell: bash
+
+  - language: yaml
+    label: "GitHub-hosted runner — explicit lfs: true with verification"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            lfs: true
+            # lfs: true is usually sufficient on GitHub-hosted runners
+            # if LFS quota is not exhausted
+prevention:
+  - "Verify git-lfs is installed on all self-hosted runners before running checkout workflows."
+  - "Monitor GitHub LFS bandwidth usage in repository Settings > Billing to avoid silent quota exhaustion."
+  - "Add a post-checkout verification step that confirms LFS-tracked files contain real content, not pointer metadata."
+  - "For fork PRs from external contributors, be aware that LFS objects may not be accessible — consider disabling LFS-dependent tests for fork builds."
+  - "Use GitHub-hosted runners for LFS-heavy workflows to avoid manual git-lfs installation and configuration."
+docs:
+  - url: "https://stackoverflow.com/questions/61463578/github-actions-actions-checkoutv2-lfs-true-flag-not-converting-pointers-to-actual-files"
+    label: "Stack Overflow: actions/checkout lfs:true not converting pointers to actual files (Score: 48, 21K views)"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: lfs input documentation"
+  - url: "https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage"
+    label: "GitHub Docs: About Git Large File Storage"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage"
+    label: "GitHub Docs: About billing for Git LFS"