@htekdev/actions-debugger 1.0.76 → 1.0.78

package/errors/runner-environment/macos-15-python-command-not-found.yml

@@ -0,0 +1,103 @@
+id: runner-environment-142
+title: "macOS-15 Sequoia Removes system python and python2 Stubs — Command Not Found in Workflows"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-15
+  - macos-latest
+  - python2
+  - python
+  - sequoia
+  - setup-python
+patterns:
+  - regex: 'python[23]?: command not found'
+    flags: 'i'
+  - regex: '/usr/bin/python.*[Nn]o such file'
+    flags: ''
+  - regex: 'xcrun: error:.*python.*not a developer tool'
+    flags: 'i'
+  - regex: 'env: python: No such file or directory'
+    flags: ''
+error_messages:
+  - "python: command not found"
+  - "python2: command not found"
+  - "/usr/bin/python: No such file or directory"
+  - "env: python: No such file or directory"
+  - "xcrun: error: unable to find utility 'python', not a developer tool or in PATH"
+root_cause: |
+  Apple removed all Python stubs from macOS in macOS 15 (Sequoia). On macOS 12 through 14,
+  running `python` or `python2` would show a dialog prompting users to install Command Line
+  Tools, but the stub binary was present in /usr/bin/python so the command was technically
+  found (it just exited non-zero in CI where dialogs are suppressed). macOS 15 removed
+  these stubs entirely — /usr/bin/python and /usr/bin/python2 no longer exist.
+
+  GitHub Actions macos-15 runners and macos-latest (which resolves to macos-15 on 2025+
+  runners) have no `python` or `python2` in PATH unless explicitly installed via
+  actions/setup-python or Homebrew.
+
+  Affected workflow patterns:
+  - `run: python script.py` without a preceding setup-python step
+  - Build tools that internally call `python` (node-gyp, certain CMake scripts,
+    legacy Makefiles, scons, gyp-based builds)
+  - Shell scripts with `#!/usr/bin/env python` shebangs
+  - `pip` commands (also absent without setup-python)
+
+  Python 2 is also fully removed from Homebrew — `brew install python@2` is no longer
+  available. Any remaining Python 2 dependency must be ported to Python 3.
+fix: |
+  Use actions/setup-python to install Python explicitly on macOS runners.
+  Set the python-version to the version your workflow needs (3.12 or higher recommended).
+
+  For node-gyp or native module builds that internally call `python`, set the
+  npm_config_python environment variable to point to the Python 3 binary from
+  setup-python.
+
+  For shell scripts with `#!/usr/bin/env python` shebangs, update the shebang to
+  `#!/usr/bin/env python3` or call the script explicitly with `python3 script.py`.
+fix_code:
+  - language: yaml
+    label: "Add actions/setup-python before any step that needs python"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: Run script
+              run: python script.py       # resolves to Python 3.12 from setup-python
+  - language: yaml
+    label: "Fix node-gyp calling python internally (native npm modules)"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.12'
+        - name: Install native modules
+          env:
+            npm_config_python: ${{ env.pythonLocation }}/bin/python3
+          run: npm ci
+  - language: yaml
+    label: "Cache Python between runs on macOS for faster CI"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.12'
+            cache: 'pip'           # caches pip downloads automatically
+        - run: pip install -r requirements.txt
+prevention:
+  - "Always use actions/setup-python on macOS jobs — never rely on system Python."
+  - "Search workflow files for bare `python` calls (without `3` suffix) and update to `python3` or add setup-python."
+  - "When migrating from macos-13 or macos-14 to macos-15, audit all steps invoking build tools (node-gyp, CMake, scons) that may call `python` internally."
+  - "Pin macos runner versions (e.g., macos-14) and plan an explicit upgrade window when testing macOS version bumps."
+docs:
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS-15 runner image readme"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python"
+  - url: "https://developer.apple.com/documentation/xcode-release-notes/xcode-16-release-notes"
+    label: "Xcode 16 Release Notes (ships with macOS-15 runners)"

package/errors/runner-environment/ubuntu-24-glibc-binary-incompatibility.yml

@@ -0,0 +1,117 @@
+id: runner-environment-139
+title: "Binaries Built on ubuntu-24.04 Require GLIBC 2.39 — Fail to Execute on ubuntu-22.04 Targets"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - ubuntu-latest
+  - glibc
+  - binary-compatibility
+  - linker
+  - distribution
+patterns:
+  - regex: 'version ''GLIBC_2\.3[6-9]'' not found'
+    flags: 'i'
+  - regex: 'libc\.so\.[0-9]+: version ''GLIBC_'
+    flags: 'i'
+  - regex: 'GLIBC_2\.3[6-9] not found \(required by'
+    flags: 'i'
+error_messages:
+  - "/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.38' not found (required by ./myapp)"
+  - "/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found (required by ./myapp)"
+  - "GLIBC_2.39 not found (required by /usr/local/bin/app)"
+  - "version 'GLIBC_2.38' not found"
+root_cause: |
+  GitHub Actions ubuntu-24.04 runners ship with GLIBC 2.39 (GNU C Library). When a
+  binary is compiled or dynamically linked on ubuntu-24.04, the resulting ELF binary
+  records minimum GLIBC version requirements based on the newest symbol version used —
+  either directly or via a linked shared library. If any symbol first introduced in
+  GLIBC 2.36–2.39 is referenced, the binary will fail to load on older systems.
+
+  GLIBC versions by runner image:
+  - ubuntu-20.04: GLIBC 2.31
+  - ubuntu-22.04: GLIBC 2.35
+  - ubuntu-24.04: GLIBC 2.39
+
+  This affects workflows that:
+  1. Build release binaries on ubuntu-latest (which resolved to ubuntu-24.04 in mid-2025)
+     and distribute them for Linux users on ubuntu-22.04 or older.
+  2. Produce binaries in one job on ubuntu-24.04 and run them in a matrix job on
+     ubuntu-22.04 — the artifact fails to execute in the older-runner job.
+  3. Build Docker images using ubuntu-24.04 as the build stage but target a
+     FROM ubuntu:22.04 or FROM debian:bookworm base image in the runtime stage.
+
+  The error only surfaces at execution time, not at compile or link time. The
+  binary appears healthy; only when it is actually run on the older system does
+  the dynamic linker report the missing GLIBC version.
+fix: |
+  Option 1 — Pin the build runner to the oldest supported OS:
+    Use ubuntu-22.04 as the build runner to ensure binaries link against GLIBC 2.35,
+    which is compatible with both ubuntu-22.04 and ubuntu-24.04 targets.
+
+  Option 2 — Build inside a container matching the target OS:
+    Use a Docker container (e.g., ubuntu:22.04) in the build job so the compiler
+    links against the correct GLIBC version regardless of the host runner.
+
+  Option 3 — Cross-compile with musl-libc (static, no GLIBC dependency):
+    For Rust, use the x86_64-unknown-linux-musl target. For C/C++, use musl-gcc or
+    musl-cross. The resulting binary has no GLIBC dependency and runs anywhere.
+
+  Option 4 — Verify GLIBC requirement in CI:
+    Add a validation step that runs objdump or readelf to assert the binary's
+    minimum GLIBC requirement before it reaches distribution.
+fix_code:
+  - language: yaml
+    label: "Pin build runner to ubuntu-22.04 for GLIBC 2.35 compatibility"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04   # GLIBC 2.35 — compatible with ubuntu-22.04 targets
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build binary
+              run: cargo build --release
+            - uses: actions/upload-artifact@v4
+              with:
+                name: my-binary
+                path: target/release/myapp
+  - language: yaml
+    label: "Build inside a Docker container targeting ubuntu:22.04"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:22.04
+          steps:
+            - name: Install build tools
+              run: |
+                apt-get update
+                apt-get install -y build-essential curl
+            - uses: actions/checkout@v4
+            - name: Build binary
+              run: make release
+  - language: yaml
+    label: "Rust: build static binary with musl (no GLIBC dependency)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Add musl target
+              run: rustup target add x86_64-unknown-linux-musl
+            - name: Build static binary
+              run: cargo build --release --target x86_64-unknown-linux-musl
+prevention:
+  - "Pin the build runner to the oldest Linux OS your users run when distributing compiled binaries."
+  - "Test binary artifacts in a matrix that includes the oldest supported runner (ubuntu-22.04) as a separate job."
+  - "Use `objdump -T myapp | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1` to check the minimum GLIBC version before release."
+  - "For maximum portability, use musl-libc or static linking to eliminate the GLIBC runtime dependency entirely."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub-hosted runners: available images"
+  - url: "https://wiki.ubuntu.com/Releases"
+    label: "Ubuntu release versions and GLIBC versions"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image readme"

package/errors/runner-environment/ubuntu-24-mysql-84-native-password-removed.yml

@@ -0,0 +1,104 @@
+id: runner-environment-141
+title: "ubuntu-24.04 MySQL 8.4 Removes mysql_native_password Plugin — Client Authentication Fails"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - mysql
+  - mysql-8.4
+  - authentication
+  - service-container
+  - database
+patterns:
+  - regex: 'Plugin ''mysql_native_password'' is not loaded'
+    flags: 'i'
+  - regex: 'mysql_native_password.*cannot be loaded'
+    flags: 'i'
+  - regex: 'ER_NOT_SUPPORTED_AUTH_MODE'
+    flags: 'i'
+  - regex: 'Client does not support authentication protocol requested by server'
+    flags: 'i'
+error_messages:
+  - "ERROR 1524 (HY000): Plugin 'mysql_native_password' is not loaded"
+  - "Authentication plugin 'mysql_native_password' cannot be loaded"
+  - "ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server; consider upgrading MySQL client"
+root_cause: |
+  Ubuntu 24.04 ships MySQL 8.4 LTS as its default MySQL version. MySQL 8.4 permanently
+  removed the `mysql_native_password` authentication plugin that was deprecated in
+  MySQL 8.0.4 and disabled by default in MySQL 8.0.34. In MySQL 8.4, the plugin
+  binary no longer exists — it cannot be re-enabled via server configuration.
+
+  The new default authentication plugin is `caching_sha2_password`, which requires
+  either a TLS/SSL connection or an RSA public key exchange during authentication.
+  Older MySQL client libraries that were compiled expecting mysql_native_password
+  behavior cannot authenticate against MySQL 8.4.
+
+  Commonly affected clients in GitHub Actions workflows:
+  - mysql2 Ruby gem versions < 0.5.6
+  - mysqljs/mysql npm package (use mysql2 npm package instead)
+  - mysql-connector-python < 8.0.28 without SSL configuration
+  - phpMyAdmin and other tools linking against older libmysqlclient
+
+  Workflows that use `image: mysql:latest` in service containers are at highest risk
+  as mysql:latest advanced to 8.4 and then 9.x after ubuntu-24.04 was released.
+fix: |
+  Option 1 — Pin MySQL service container to mysql:8.0:
+    Use `image: mysql:8.0` in your service container definition. MySQL 8.0 supports
+    mysql_native_password and is fully compatible with existing client libraries.
+    This is the fastest fix for affected workflows.
+
+  Option 2 — Update the MySQL client library:
+    - Ruby: upgrade mysql2 gem to >= 0.5.6 (caching_sha2_password support added)
+    - Node.js: replace `mysql` package with `mysql2` (>= 3.x)
+    - Python: upgrade mysql-connector-python to latest and configure ssl_disabled: false
+
+  Option 3 — Configure MySQL 8.4 to allow password auth with --default-auth:
+    MySQL 8.4 still supports caching_sha2_password for all connections. The issue is
+    the client, not the server. Update the client library — not the server auth policy.
+fix_code:
+  - language: yaml
+    label: "Pin MySQL service container to 8.0 to preserve native password support"
+    code: |
+      services:
+        mysql:
+          image: mysql:8.0          # Pin — mysql:latest is now 8.4+ (native_password removed)
+          env:
+            MYSQL_ROOT_PASSWORD: rootpassword
+            MYSQL_DATABASE: testdb
+          options: >-
+            --health-cmd="mysqladmin ping -h 127.0.0.1"
+            --health-interval=10s
+            --health-timeout=5s
+            --health-retries=5
+  - language: yaml
+    label: "Update mysql2 Ruby gem and use mysql:8.4 correctly"
+    code: |
+      # Gemfile — update to mysql2 >= 0.5.6 for caching_sha2_password support
+      # gem 'mysql2', '>= 0.5.6'
+
+      # Node.js — replace mysql (1.x) with mysql2 (3.x)
+      # npm install mysql2    # supports SHA2 auth; old mysql package does not
+
+      services:
+        mysql:
+          image: mysql:8.4
+          env:
+            MYSQL_ROOT_PASSWORD: rootpassword
+            MYSQL_DATABASE: testdb
+          options: >-
+            --health-cmd="mysqladmin ping -h 127.0.0.1"
+            --health-interval=10s
+            --health-timeout=5s
+            --health-retries=5
+prevention:
+  - "Always pin service container image versions (e.g., mysql:8.0) — mysql:latest advances silently and introduces breaking changes."
+  - "Test with the exact MySQL version your production environment uses, not mysql:latest."
+  - "When upgrading MySQL service container versions, update client gems/packages to versions that support caching_sha2_password."
+  - "Use the mysql health check option to fail fast when the container is misconfigured rather than timing out later."
+docs:
+  - url: "https://dev.mysql.com/doc/relnotes/mysql/8.4/en/news-8-4-0.html"
+    label: "MySQL 8.4.0 Release Notes — mysql_native_password removed"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers"
+    label: "GitHub Actions: about service containers"
+  - url: "https://github.com/brianmario/mysql2"
+    label: "mysql2 Ruby gem — caching_sha2_password support"

package/errors/runner-environment/ubuntu-24-pip-externally-managed-environment.yml

@@ -0,0 +1,90 @@
+id: runner-environment-140
+title: "ubuntu-24.04 pip install Fails With 'externally-managed-environment' — PEP 668 Blocks System Python"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - ubuntu-latest
+  - python
+  - pip
+  - pep-668
+  - venv
+patterns:
+  - regex: 'error: externally-managed-environment'
+    flags: 'i'
+  - regex: 'This environment is externally managed'
+    flags: 'i'
+  - regex: 'EXTERNALLY-MANAGED'
+    flags: ''
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "hint: See PEP 668 for the detailed specification."
+root_cause: |
+  Ubuntu 24.04 implements PEP 668, which marks the system Python environment as
+  "externally managed" — pip is not permitted to install or modify packages into
+  the system Python site-packages directory. The restriction is enforced by an
+  EXTERNALLY-MANAGED marker file placed at /usr/lib/python3.X/EXTERNALLY-MANAGED
+  by the Ubuntu package maintainers.
+
+  On GitHub Actions ubuntu-24.04 runners (and ubuntu-latest, which resolved to
+  ubuntu-24.04 in mid-2025), the default system Python 3 (3.12) ships this marker.
+  Any workflow step that calls `pip install` or `pip3 install` without a virtual
+  environment or the setup-python action will hit this error immediately.
+
+  Workflows migrated from ubuntu-22.04 — which did not enforce PEP 668 — will fail
+  on first run without any other changes. The error is clear in the output but
+  unexpected for workflows that previously relied on system-wide pip installs.
+fix: |
+  Option 1 — Use actions/setup-python (recommended):
+    Replace the bare system Python with a setup-python step. actions/setup-python
+    creates its own isolated Python installation outside the system path, making
+    pip install work without virtual environments or bypass flags.
+
+  Option 2 — Create a virtual environment:
+    Run `python3 -m venv .venv && source .venv/bin/activate` before pip install.
+    This is the correct long-term fix for any environment.
+
+  Option 3 — Pass --break-system-packages:
+    Append `--break-system-packages` to the pip install command. This bypasses
+    PEP 668 enforcement. Acceptable in ephemeral CI environments but not
+    recommended for production systems.
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python — recommended approach"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.12'
+        - name: Install dependencies
+          run: pip install -r requirements.txt   # works: isolated Python, not system
+  - language: yaml
+    label: "Create a virtual environment before pip install"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Install in venv
+          run: |
+            python3 -m venv .venv
+            source .venv/bin/activate
+            pip install -r requirements.txt
+  - language: yaml
+    label: "Quick fix: --break-system-packages flag (CI-only workaround)"
+    code: |
+      steps:
+        - name: Install dependencies
+          run: pip install --break-system-packages -r requirements.txt
+prevention:
+  - "Use actions/setup-python on ubuntu-24.04 runners — do not rely on system Python for pip installs."
+  - "Audit all `pip install` steps when migrating from ubuntu-22.04 to ubuntu-24.04 or ubuntu-latest."
+  - "Pin your Python version in actions/setup-python to prevent unexpected changes when the runner default Python changes."
+  - "Cache the virtual environment with actions/cache using a hash of requirements.txt as the key to speed up runs."
+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"
+    label: "actions/setup-python"
+  - url: "https://wiki.ubuntu.com/NobleNumbat/ReleaseNotes"
+    label: "Ubuntu 24.04 (Noble Numbat) Release Notes"

package/errors/runner-environment/ubuntu-snap-not-available-no-systemd.yml

@@ -0,0 +1,92 @@
+id: runner-environment-143
+title: "snap install Fails on All GitHub-Hosted Runners — snapd Requires systemd Which Is Absent in CI"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - snap
+  - snapd
+  - systemd
+  - package-management
+  - runner-limitation
+patterns:
+  - regex: 'cannot communicate with server.*snapd'
+    flags: 'i'
+  - regex: 'snap: command not found'
+    flags: 'i'
+  - regex: 'snapd\.socket.*connect.*no such file'
+    flags: 'i'
+  - regex: 'error: cannot list snaps: cannot communicate with server'
+    flags: 'i'
+error_messages:
+  - "error: cannot communicate with server: Post \"http+unix://%2Frun%2Fsnapd.socket/v2/snaps\": dial unix /run/snapd.socket: connect: no such file or directory"
+  - "snapd is not running"
+  - "snap: command not found"
+  - "cannot communicate with server: Post http+unix:///run/snapd.socket/v2/snaps: dial unix /run/snapd.socket: connect: no such file or directory"
+root_cause: |
+  GitHub-hosted Ubuntu runners do not run systemd as PID 1. They use a custom
+  initialization environment where systemd is not the init system. The snap package
+  manager (snapd) requires systemd for:
+  - Daemon lifecycle management (snapd.service unit)
+  - D-Bus socket activation (/run/snapd.socket)
+  - AppArmor profile enforcement for snap confinement
+  - Mount namespace management for snap application isolation
+
+  Without systemd, the snapd daemon never starts, and /run/snapd.socket does not
+  exist. Any `snap install` command immediately fails because the snap client
+  cannot reach the daemon socket to submit the install request.
+
+  This is a structural limitation of GitHub-hosted runners across ALL Ubuntu versions
+  (ubuntu-20.04, ubuntu-22.04, ubuntu-24.04, ubuntu-latest) and has not changed
+  since Actions was launched. Attempting to start snapd manually with `systemctl start snapd`
+  also fails because systemctl is non-functional without systemd.
+
+  While `snap` binary may be present in PATH on some runner images, it is non-functional
+  and the underlying daemon cannot be started in the current runner architecture.
+fix: |
+  Replace snap install with an alternative package source:
+
+  - Use apt/apt-get: Most snap packages have apt equivalents or PPA repositories
+  - Use dedicated GitHub Actions: Many popular tools have official or maintained Actions
+    (e.g., azure/setup-kubectl, helm/kind-action, hashicorp/setup-terraform)
+  - Download official binary releases: curl the release binary from GitHub Releases
+    or the tool's official download page, then move to /usr/local/bin
+  - Use Homebrew (macOS) or the tool's official install script
+fix_code:
+  - language: yaml
+    label: "Replace snap install kubectl with the official setup-kubectl action"
+    code: |
+      steps:
+        # Instead of: run: sudo snap install kubectl --classic
+        - uses: azure/setup-kubectl@v4
+          with:
+            version: 'v1.30.0'
+  - language: yaml
+    label: "Replace snap install helm with the official Helm install script"
+    code: |
+      steps:
+        # Instead of: run: sudo snap install helm --classic
+        - name: Install Helm
+          run: |
+            curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+  - language: yaml
+    label: "Generic: replace snap install with direct binary download"
+    code: |
+      steps:
+        - name: Install tool via binary release (snap alternative)
+          run: |
+            VERSION="1.2.3"
+            curl -fsSL "https://example.com/releases/${VERSION}/tool-linux-amd64.tar.gz" \
+              | tar -xz -C /usr/local/bin tool
+prevention:
+  - "Never use `snap install` in GitHub Actions — snapd does not work on any GitHub-hosted runner."
+  - "Search all workflow files for `snap install` and replace with apt, binary downloads, or official GitHub Actions."
+  - "When evaluating new tools for CI, prefer those distributed via apt, Homebrew, or binary releases over snap-only distributions."
+  - "Check the tool's GitHub repository for an official GitHub Action before writing a custom install step."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/3206"
+    label: "runner-images #3206: snap install fails on GitHub Actions (long-running issue)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub-hosted runners overview"
+  - url: "https://snapcraft.io/docs/installing-snapd"
+    label: "Snapcraft: installing snapd (requires systemd)"

package/errors/silent-failures/inputs-context-empty-on-non-dispatch-event.yml

@@ -0,0 +1,96 @@
+id: silent-failures-072
+title: "inputs Context Empty on Non-Dispatch Events — Multi-Trigger Workflows Leave inputs.* as Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - inputs
+  - workflow-dispatch
+  - push
+  - multi-trigger
+  - context
+  - empty-string
+patterns:
+  - regex: 'inputs\.[a-zA-Z_][a-zA-Z0-9_-]* (?:is empty|not set|undefined|was null)'
+    flags: 'i'
+error_messages:
+  - "Deploy target is empty — expected inputs.environment to be non-empty"
+  - "Error: Input required and not supplied: environment"
+root_cause: |
+  The `inputs` context in GitHub Actions is ONLY populated when a workflow is triggered
+  by a `workflow_dispatch` or `workflow_call` event. When the same workflow is triggered
+  by any other event — push, pull_request, schedule, release, workflow_run, etc. — the
+  entire `inputs` context is empty. Every `${{ inputs.anything }}` expression evaluates
+  to `""` (empty string) without raising an error or printing a warning.
+
+  This commonly affects developers who:
+  1. Add `on: workflow_dispatch` with inputs to an existing push-triggered workflow
+     to enable manual override capability.
+  2. Reference `${{ inputs.environment }}` or `${{ inputs.deploy_target }}` in `run:`
+     steps, `with:` parameters, or `env:` blocks — expecting a sensible default when
+     triggered automatically by push.
+  3. Use `if: inputs.skip_tests == 'true'` — on push events this is effectively
+     `if: '' == 'true'` which evaluates to false silently.
+  4. Pass `${{ inputs.version }}` to an action's `with: version:` parameter — the
+     action receives an empty string and may silently use its own default or fail
+     with an opaque "invalid version" message.
+
+  The `inputs` context is distinct from `github.event.inputs` (legacy alias, same
+  empty behavior on non-dispatch events) and from the `vars` context (org/repo
+  configuration variables which are always populated).
+fix: |
+  Use the `||` fallback operator to provide defaults for all inputs in workflows
+  that support multiple triggers. This guarantees non-dispatch triggers receive
+  a sensible default instead of an empty string.
+
+  Guard dispatch-only logic blocks with `if: github.event_name == 'workflow_dispatch'`
+  to explicitly skip input-dependent steps on automated trigger runs.
+fix_code:
+  - language: yaml
+    label: "Provide fallback defaults for all inputs in multi-event workflows"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [staging, production]
+              default: staging
+            skip_tests:
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            # Use || to fall back to defaults when triggered by push
+            DEPLOY_ENV: ${{ inputs.environment || 'staging' }}
+            SKIP_TESTS: ${{ inputs.skip_tests || 'false' }}
+          steps:
+            - name: Deploy
+              run: echo "Deploying to $DEPLOY_ENV (skip_tests=$SKIP_TESTS)"
+  - language: yaml
+    label: "Guard input-dependent logic with event_name check"
+    code: |
+      steps:
+        - name: Apply manual override (dispatch only)
+          if: github.event_name == 'workflow_dispatch'
+          run: echo "Manual dispatch with environment=${{ inputs.environment }}"
+
+        - name: Default automated deploy
+          if: github.event_name != 'workflow_dispatch'
+          run: echo "Automated push deploy to staging"
+prevention:
+  - "Always use `${{ inputs.param || 'default' }}` when a workflow supports more than one trigger — never assume inputs will be populated."
+  - "Log `github.event_name` at the start of the workflow to trace which trigger fired and aid debugging of empty-input behavior."
+  - "Use the 'Context availability' table in GitHub Actions documentation to verify which contexts are populated for each event type before referencing them."
+  - "Consider splitting dispatch workflows (with inputs) from automated trigger workflows — combining both in one file with shared input-referencing code is a common source of subtle bugs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#inputs-context"
+    label: "GitHub Actions: inputs context"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "workflow_dispatch event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "Context availability by event type"

package/errors/silent-failures/vars-context-undefined-variable-empty-string.yml

@@ -0,0 +1,84 @@
+id: silent-failures-073
+title: "vars. Context Returns Empty String for Undefined Organization or Repository Variables — No Error Raised"
+category: silent-failures
+severity: silent-failure
+tags:
+  - vars
+  - configuration-variables
+  - context
+  - empty-string
+  - organization
+  - repository
+patterns:
+  - regex: 'vars\.[A-Z_][A-Z0-9_]* (?:is empty|not set|missing|undefined|not defined)'
+    flags: 'i'
+error_messages:
+  - "Error: REGISTRY_URL is empty — check that vars.REGISTRY_URL is defined in repository variables"
+  - "Error: docker tag '' is not valid"
+  - "fatal: repository '' does not exist"
+root_cause: |
+  GitHub Actions configuration variables (the `vars` context, introduced 2023) provide a
+  non-secret key/value store at the organization, repository, or environment level. When
+  a `${{ vars.MY_VARIABLE }}` expression references a variable that has not been defined
+  at any applicable scope, the expression evaluates to `""` (empty string) without
+  raising any error, warning, or annotation in the Actions run UI.
+
+  Unlike missing secrets (which also silently return empty string), `vars` variables are
+  user-visible and frequently forgotten when:
+  1. A workflow is used in a new repository that hasn't had its variables configured.
+  2. A variable is defined at the repository level but the job targets an environment
+     that doesn't inherit repo-level variables (environment-scoped variables override
+     but do not merge with repo-scoped variables of the same name).
+  3. A variable is defined only at the organization level but the repository is
+     a fork — forked repositories cannot access parent org variables.
+  4. The variable name has a typo in the workflow file.
+
+  Silent empty values cascade into confusing downstream errors: Docker tags become `":latest"`
+  instead of `"ghcr.io/org/image:latest"`, API endpoints receive empty base URLs, and
+  notification webhooks silently fail with HTTP 400.
+
+  Environment-scoped variables are ONLY available when the job specifies `environment:`.
+  If a job has no `environment:` key, env-scoped variables are not available even if
+  the env-scoped variable has the same name as a repo-scoped variable.
+fix: |
+  Use the `||` fallback operator to provide safe defaults, and add an explicit
+  validation step for variables that are required for the workflow to succeed.
+fix_code:
+  - language: yaml
+    label: "Use || fallback for optional vars"
+    code: |
+      env:
+        REGISTRY: ${{ vars.REGISTRY_URL || 'ghcr.io' }}
+        LOG_LEVEL: ${{ vars.LOG_LEVEL || 'info' }}
+        API_BASE: ${{ vars.API_BASE_URL || 'https://api.example.com' }}
+  - language: yaml
+    label: "Validate required vars at workflow start with fail-fast"
+    code: |
+      jobs:
+        preflight:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate required configuration variables
+              env:
+                REGISTRY_URL: ${{ vars.REGISTRY_URL }}
+                DEPLOY_ENV: ${{ vars.DEPLOY_ENV }}
+              run: |
+                missing=()
+                [ -z "$REGISTRY_URL" ] && missing+=("vars.REGISTRY_URL")
+                [ -z "$DEPLOY_ENV" ]   && missing+=("vars.DEPLOY_ENV")
+                if [ ${#missing[@]} -gt 0 ]; then
+                  echo "::error::Missing required variables: ${missing[*]}"
+                  echo "Set them at: Settings → Secrets and Variables → Variables"
+                  exit 1
+                fi
+prevention:
+  - "Document all required `vars.*` variables in the repository README or CONTRIBUTING guide — unlike required inputs, they have no built-in validation."
+  - "Add a preflight validation job that checks for required variables and fails immediately with a clear error message."
+  - "Use `${{ vars.SETTING || 'sensible-default' }}` consistently to make empty-variable behavior explicit."
+  - "For environment-scoped variables, ensure the job specifies `environment:` — variables defined only on an environment are not available to jobs that omit the environment key."
+  - "Use repository variable naming conventions (UPPER_SNAKE_CASE) and check for typos in workflow YAML against the variables defined in Settings."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Actions: configuration variables (vars context)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#vars-context"
+    label: "vars context reference"

package/errors/yaml-syntax/env-variable-name-dot-expression-subproperty-access.yml

@@ -0,0 +1,101 @@
+id: yaml-syntax-049
+title: "env Variable Name with Dots — ${{ env.MY.VAR }} Silently Reads Undefined Subproperty"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - env-context
+  - expression-syntax
+  - dots
+  - property-access
+  - empty-string
+  - naming
+patterns:
+  - regex: '\$\{\{\s*env\.[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_]'
+    flags: ''
+  - regex: '\$\{\{\s*vars\.[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_]'
+    flags: ''
+error_messages:
+  - "Error: Expected non-empty value but got '' (env.MY.VAR resolved to empty string)"
+  - "::error::Variable 'app.version' is empty — check expression syntax"
+root_cause: |
+  GitHub Actions expression syntax uses the dot (`.`) character as a property accessor
+  for traversing nested context objects. When an environment variable name contains a
+  dot (e.g., `MY.VAR`, `app.version`, `node.options`), the expression `${{ env.MY.VAR }}`
+  is evaluated by the expression parser as two sequential property dereferences:
+
+  1. `env.MY` — look up the property named exactly `MY` on the env object
+  2. `.VAR`   — look up the property named `VAR` on the result of step 1
+
+  If no environment variable named exactly `MY` exists (only `MY.VAR` does), then
+  `env.MY` returns `""` (empty string), and the entire expression silently evaluates
+  to `""` with no error or warning.
+
+  This is legal YAML — `env: MY.VAR: 'hello'` is valid YAML syntax and DOES set the
+  shell environment variable `MY.VAR` in `run:` steps. Linux and macOS allow dots in
+  env var names. The problem is exclusively in the expression layer: `${{ env.MY.VAR }}`
+  cannot reach the variable because `.` is an operator, not part of the identifier.
+
+  The same issue affects the `vars` context: `${{ vars.app.version }}` attempts to
+  read a sub-property `version` of a variable named `app`, not a variable named
+  `app.version`.
+
+  actionlint does not currently warn on dotted env/vars expressions because the
+  expression syntax is technically valid — it just resolves to empty string at runtime.
+fix: |
+  Option 1 — Rename environment variables to use underscores instead of dots (recommended):
+    Change `MY.VAR` to `MY_VAR`. This is the POSIX-conventional approach and works
+    reliably with all GitHub Actions expression syntax.
+
+  Option 2 — Use bracket property accessor syntax:
+    `${{ env['MY.VAR'] }}` uses the array/bracket notation which treats the entire
+    string `MY.VAR` as a single property key, correctly reading the dotted variable.
+
+  Option 3 — Access the variable via shell syntax in run: steps:
+    In `run:` steps the shell receives the full env var with its dotted name. Use
+    the shell variable reference directly in shell scripts, not in expressions.
+fix_code:
+  - language: yaml
+    label: "Rename to underscores (recommended)"
+    code: |
+      env:
+        MY_VAR: 'hello'        # was MY.VAR — underscore works in expressions
+        APP_VERSION: '1.2.3'   # was app.version
+
+      steps:
+        - name: Read variable
+          run: echo "Version is ${{ env.APP_VERSION }}"
+  - language: yaml
+    label: "Bracket syntax for dotted env var names"
+    code: |
+      env:
+        MY.VAR: 'hello'         # dotted name is set in the shell env
+
+      steps:
+        - name: Read via bracket syntax
+          run: echo "Value is ${{ env['MY.VAR'] }}"
+          # BAD:  ${{ env.MY.VAR }}     → silently reads undefined subproperty
+          # GOOD: ${{ env['MY.VAR'] }}  → reads the full dotted variable name
+  - language: yaml
+    label: "Access dotted env var directly in shell (run: steps only)"
+    code: |
+      env:
+        MY.VAR: 'hello'
+
+      steps:
+        - name: Use shell variable directly
+          run: |
+            # The shell receives the env var with its dotted name
+            # Access it via indirect parameter expansion
+            VAR_NAME='MY.VAR'
+            echo "${!VAR_NAME}"   # bash indirect expansion
+prevention:
+  - "Never use dots in environment variable names in `env:` blocks — always use UPPER_SNAKE_CASE with underscores."
+  - "When consuming third-party tooling that sets dotted env var names, immediately re-export them with underscore names for safe use in expressions."
+  - "Review any expression containing two dots in the same context path (e.g., `env.a.b`) — this almost always indicates a naming mistake."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#env-context"
+    label: "GitHub Actions: env context"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#property-dereference"
+    label: "Property dereference in expressions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "Evaluate expressions in workflows and actions"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",