Skip to content
Latchkey
EnglishPortuguês日本語
Start Free
GitHub Actions

Workflow, runner, and YAML errors - diagnosed and fixed.

Fix the most common GitHub Actions failures: workflow syntax errors, runner problems, permission and authentication issues, caching, and matrix builds. Clear causes, copy-paste fixes, and how to stop them recurring.

Workflow & YAML syntax

Invalid workflow files, expressions, and triggers.

paths-filter falseFix dorny/paths-filter outputs always coming back false - a shallow checkout with no base ref, a missing id, "Step cannot have both uses and run"Fix GitHub Actions "a step cannot have both the uses and run keys" - a single step mixed an action reference "workflow_dispatch not available"Fix a missing Run workflow button or dispatch error caused by the workflow_dispatch trigger not existing on "fatal: detached HEAD"Fix GitHub Actions git operations failing because actions/checkout leaves the repo on a detached HEAD at a "fromJson: Unable to parse"Fix GitHub Actions "Unable to parse" from fromJSON in CI - the string handed to fromJSON was not valid JSON, "Invalid pattern"Fix GitHub Actions "Invalid pattern `x`" - a malformed glob in a paths, paths-ignore, branches, or tags "Job has been skipped"Fix a GitHub Actions job that is skipped because a job in its needs was skipped or failed - downstream jobs Matrix configuration errorFix GitHub Actions matrix errors - empty matrix, bad include/exclude shape, or referencing a matrix key that "Missing environment 'production'"Fix the GitHub Actions missing-environment error - a job references an environment that does not exist in the "No event triggers defined in 'on'"Fix GitHub Actions "No event triggers defined in 'on'" in CI - the `on` key is present but empty or exit code 1 (set -e)Fix a GitHub Actions run step that fails with exit code 1 due to the default bash set -e - any failing "shell: pwsh" not availableFix the GitHub Actions error where a step with "shell: pwsh" fails on an Ubuntu runner because PowerShell app cannot update workflowFix "refusing to allow a GitHub App to create or update workflow" - the token lacks the workflows permission "Reusable workflow was not found"Fix GitHub Actions "reusable workflow was not found" - a uses: to a called workflow points at a path or ref "workflow file is invalid on this ref"Fix a required check that is silently skipped because the workflow file is invalid on the PR base or head ref. "startup_failure"Fix GitHub Actions runs that end in startup_failure - an invalid workflow file, a bad reference, or a config "The expression is too long"Fix the GitHub Actions "expression is too long (max 21000 chars)" error - a single \${{ }} template exceeds "requested workflow was not found at ref"Fix "The requested workflow was not found" when dispatching or referencing a workflow that does not exist on "This check was cancelled"Fix a required status check that blocks merge after being cancelled by a job timeout or concurrency depends on a skipped jobFix a GitHub Actions job that will not run because a job it depends on was skipped - skips propagate through "jobs section required"Fix GitHub Actions "The top level `jobs` section is required" - a missing, empty, or misindented jobs: block, "Unable to interpret as boolean"Fix GitHub Actions "Unable to interpret 'X' as a boolean" - a key expecting true/false received a non-boolean "Unable to resolve action"Fix GitHub Actions "Unable to resolve action" / "repository not found" - a wrong uses: path, a non-existent "Unexpected input(s), valid inputs are"Fix GitHub Actions "Unexpected input(s) ..., valid inputs are ..." - the with: block passed an input the "Unexpected symbol"Fix the GitHub Actions "Unexpected symbol" expression error caused by invalid operators, stray characters, or "Unexpected value"Fix the GitHub Actions "The workflow is not valid ... (Line: N): Unexpected value" error caused by a key in "Unrecognized named-value: 'matrix'"Fix "Unrecognized named-value: 'matrix'" in GitHub Actions - the matrix context was referenced where it is "named-value: inputs"Fix GitHub Actions "Unrecognized named-value: inputs" - using the inputs context in a workflow that has no "Unrecognized named-value: 'secrets'"Fix the GitHub Actions expression error "Unrecognized named-value: secrets" caused by using a context where "Unrecognized named-value"Fix GitHub Actions "Unrecognized named-value" and expression errors - referencing a context that is not "working-directory does not exist"Fix the GitHub Actions error where a step fails because its working-directory path does not exist on the Submodule checkout failsFix actions/checkout submodule failures - submodules: true needs a token with access to private submodule github.action_pathFix composite actions that cannot find their own bundled scripts - run steps resolve relative to the Composite action inputFix composite action input errors - undeclared inputs, the shell missing from a run step, or referencing skipped job blocks mergeFix a PR that cannot merge because a skipped conditional job leaves its required status check unfulfilled. Actions contexts availabilityWhich GitHub Actions context is available at which workflow key, why an unavailable one silently becomes an continue-on-error masks failureFix a matrix job that reports success because continue-on-error swallowed a genuinely failed combination. fromJSON matrix errorFix GitHub Actions dynamic matrix errors - a matrix built from fromJSON of a job output that is empty, not Env var not expandingFix GitHub Actions env vars that come through empty or literal - mixing ${{ }} and shell $VAR syntax, or Actions env vars referenceDefault GitHub Actions environment variables, the precedence order between workflow, job and step env, and Actions expressionsOperators, status functions, and the type-coercion rules behind GitHub Actions expressions, including why a if condition always runsFix a GitHub Actions if condition that always runs - a bare string in if is truthy, so the step never skips. if: always() misuseFix GitHub Actions if: conditions using always(), success(), failure(), and cancelled() - always() runs even always() skipped on cancelFix a GitHub Actions step using if: always() that still skips - a canceled workflow short-circuits most steps matrix include unexpected comboFix a GitHub Actions matrix where include adds or alters combinations unexpectedly - include both extends and Matrix include/excludeFix GitHub Actions matrix include/exclude surprises - include adding extra jobs, expanding existing multiline run script failsFix a GitHub Actions multiline run that breaks - the YAML block scalar indicator or indentation mangled the needs.<job>.outputs emptyFix GitHub Actions needs.<job>.outputs returning empty - the upstream job never mapped its step output to a paths filter confusionFix GitHub Actions paths and paths-ignore confusion - they are mutually exclusive per event, use glob rules, missing pipefail in pipeFix a GitHub Actions run where a failing command in a pipe is ignored - a custom shell without pipefail only pipefail masks failuresFix GitHub Actions steps that pass despite a failing command in a pipe - bash run steps set pipefail by "secret not defined"Fix GitHub Actions reusable workflow secret errors - passing a secret the called workflow never declared "reusable workflow input type mismatch"Fix the GitHub Actions error where a reusable workflow rejects a "with:" input because the value type does Input type mismatchFix GitHub Actions reusable workflow input type errors - passing a string where boolean or number is Reusable outputs emptyFix GitHub Actions reusable workflow outputs that arrive empty - workflow_call must declare outputs mapped "reusable workflow uses must be ..."Fix the GitHub Actions error where a reusable workflow uses value is not a valid "step debug logs truncated"Fix the GitHub Actions issue where verbose step debug logs are truncated in the UI, hiding the line you need. "timeout-minutes exceeded killed step"Fix the GitHub Actions error where a step or job is forcibly terminated because it ran past its steps.<id> emptyFix GitHub Actions steps.<id>.outputs coming back empty - a step with no id, a typo in the id, or reading the success() and failure() both falseFix a cleanup step that never runs because both success() and failure() are false during a cancellation. Actions workflow triggersEvery GitHub Actions trigger event with the scoping rules that decide whether a workflow runs, including the env not inheritedFix GitHub Actions env vars that are empty inside a called reusable workflow - env does not cross the env not visible in run-nameFix a run-name that renders blank or literal because it references env, which is not available in the working-directory ignored (uses)Fix a step where working-directory has no effect because it only applies to run steps, not uses steps. YAML anchors unsupportedUnderstand why GitHub Actions does not expand YAML anchors/aliases (&, *, <<) for reuse - and the supported

Runners & execution

Runner startup, labels, concurrency, and timeouts.

"failed to properly upload report"Fix codecov/codecov-action "failed to properly upload report" from a transient upload failure or a missing "ERROR: failed to solve: buildkit not found"Fix docker/build-push-action "failed to solve" when docker/setup-buildx-action was not run first. "/usr/bin/bash: line N: command not found"Fix the GitHub Actions run-step error "/usr/bin/bash: line N: command not found" - the tool is not installed "Failed to create deployment" (Pages)Fix the actions/deploy-pages error "Failed to create deployment" - a permissions gap or a transient Pages API Scheduled workflow disabledFix a GitHub Actions scheduled workflow that stopped firing because it was auto-disabled after 60 days of "Hosted runner encountered an error"Fix the GitHub Actions "The hosted runner encountered an error while running your job" failure - a transient "Runner lost communication"Fix GitHub Actions "The hosted runner lost communication with the server" - a network or backend drop severed "self-hosted runner is offline"Fix jobs that never start because the targeted self-hosted runner is offline or disconnected. "Self-hosted lost connection"Fix a self-hosted GitHub Actions runner that lost connection mid-job, failing the run and dropping the runner "startup_failure"Fix a workflow run that fails with conclusion startup_failure before any job runs - usually an invalid "Codecov token required"Fix codecov/codecov-action "Token required" / tokenless rate limit - tokenless uploads are rate-limited, so a "failed to initialize builder"Fix docker/setup-buildx-action "failed to initialize builder" - buildx could not create the builder instance, Step summary missingFix GitHub Actions job summaries that do not render - writing to the wrong target, exceeding the per-step Job stuck queuedFix a GitHub Actions job stuck on "Waiting for a runner" - no runner matches the labels, the self-hosted "No pnpm version is specified"Fix pnpm/action-setup "No pnpm version is specified" - neither the version input nor packageManager in "Unable to find Go version"Fix actions/setup-go "Unable to find Go version" - the requested Go version is not published for the runner "No such file or directory @ rb_sysopen"Fix Ruby "Errno::ENOENT: No such file or directory @ rb_sysopen" on a macos-latest runner - a gem or script "nothing to commit, working tree clean"Understand stefanzweifel/git-auto-commit reporting "nothing to commit" when no files changed in the working

Permissions & secrets

GITHUB_TOKEN scopes, OIDC, and secret access.

"deploy-pages: deployment failed"Fix actions/deploy-pages deployment failures - a missing github-pages environment, branch protection rules, Environment "Required reviewers"Fix a deployment job waiting on environment "Required reviewers" in CI - the environment protection rule "denied" pushing to ghcr.ioFix the GitHub Actions error pushing an image to ghcr.io - the job is missing packages: write or the login "GITHUB_TOKEN" read-only on fork PRFix the GitHub Actions error where GITHUB_TOKEN has no write access on a forked-PR workflow run. "token not supplied"Fix GitHub Actions "Input required and not supplied: token" - an action that needs a token input but received "Pull request not mergeable"Fix a GitHub Actions auto-merge step that fails with "Pull request is not mergeable" - branch protection, "Resource not accessible by personal access token"Fix "Resource not accessible by personal access token" when a fine-grained PAT lacks the required repository "Waiting for approval to run workflows"Resolve a PR stuck at "Waiting for approval to run workflows" by having a maintainer approve the queued run. "Get Pages site failed (not enabled)"Fix actions/configure-pages "Get Pages site failed" - GitHub Pages is not enabled for the repository or not checkout persisted credentials 403Fix the GitHub Actions 403 when pushing after actions/checkout, caused by the persisted GITHUB_TOKEN lacking codecov tokenFix codecov/codecov-action upload failures - a missing CODECOV_TOKEN on private repos, a transient upload "composite action cannot access secrets"Fix the GitHub Actions error where a composite action references the secrets context directly, which is not "Username and password required"Fix docker/login-action "Error: Username and password required" - the action got an empty username or Environment secrets emptyFix GitHub Actions environment secrets that come through empty - a job must declare environment: to receive Env secret emptyFix GitHub Actions environment secrets coming through empty - environment-scoped secrets only load when the "GITHUB_TOKEN cannot access another repository"Fix cross-repository calls failing because the automatic GITHUB_TOKEN is scoped only to the workflow "workload identity audience mismatch"Fix google-github-actions/auth workload identity failures - the OIDC token audience, provider, or subject "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL"Fix the GitHub Actions OIDC error "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL" caused by the workflow missing Actions permissionsEvery GITHUB_TOKEN permission scope, which common operations require each one, and why declaring a secrets in if conditionsFix GitHub Actions where secrets in an if condition do not work - the secrets context is not available in "Get Pages site failed"Fix the github-pages error "Get Pages site failed" - Pages is not enabled or not set to GitHub Actions as the "Error: missing token"Fix ncipollo/release-action failing with a missing token error when no GITHUB_TOKEN is supplied to the "Unable to acquire impersonated credentials"Fix GCP Workload Identity "Unable to acquire impersonated credentials" in CI - the WIF pool/provider secrets: inherit missingFix GitHub Actions reusable-workflow secrets arriving empty - the caller must forward each secret explicitly "Validation Failed: already_exists"Fix softprops/action-gh-release "Validation Failed already_exists" when the tag or release already exists on

Caching & artifacts

actions/cache misses, restore keys, artifact upload.

actions/cache referenceHow actions/cache keys, restore-keys, branch scoping, the 10 GB cap and 7-day eviction actually behave, and configure-pages failedFix actions/configure-pages failing - GitHub Pages not enabled with the Actions source, or a missing pages: "Could not resolve a version... from node-version-file"Fix actions/setup-node failing to resolve a Node version from node-version-file due to a missing or malformed "name already exists"Fix GitHub Actions v4 upload "an artifact with this name already exists" - names are unique per run, so "artifact name exists"Fix GitHub Actions "Failed to CreateArtifact: an artifact with this name already exists" - v4 artifacts are "Cache already exists"Understand GitHub Actions cache immutability - once a key is saved you cannot overwrite it, so updated "Cache not found"Fix actions/cache "Cache not found for input keys" - a key that changes every run, missing restore-keys, or a "Dependencies lock file is not found"Fix GitHub Actions "Dependencies lock file is not found" from setup-node caching - the action could not "Artifact not found"Fix GitHub Actions "Failed to download artifact" - download-artifact could not find an artifact, usually a "No files found"Fix GitHub Actions upload-artifact "No files were found with the provided path" - the path glob matched "No files were found with the provided path"Fix the upload-artifact warning "No files were found with the provided path" - the path glob matched nothing, Artifact upload failedFix actions/upload-artifact@v4 failures - "No files were found with the provided path", a wrong working "reserveCache failed"Fix actions/cache reserveCache failing because the cache entry is too large or the repo cache quota is "No files were found with the provided path"Fix actions/upload-artifact@v4 "No files were found with the provided path" - the path glob matched nothing, "No Pages artifact found"Fix deploy-pages "No artifact named github-pages-artifact found" - upload-pages-artifact did not run or Artifact expiredFix GitHub Actions downloads failing because the artifact expired - artifacts have a retention period Artifact path structureFix GitHub Actions artifacts with a wrong directory structure - the common parent is stripped or multiple "Cache not updating"Fix a GitHub Actions cache that never reflects new content because the key is reused and cache entries are Cache not savedUnderstand why actions/cache does not save when the exact key already exists - caches are immutable, so a restore-keys stale matchFix GitHub Actions caches that restore an old archive via restore-keys - a too-broad prefix matches a stale metadata-action tagsFix docker/metadata-action emitting no tags - a missing images input, tag rules that match no event, or Artifact from another runFix GitHub Actions downloading an artifact created by another run - actions/download-artifact needs run-id "Unable to find artifacts"Fix GitHub Actions download-artifact "Unable to find any artifacts for the associated workflow" when no "paths not resolved"Fix the GitHub Actions setup-node cache warning "Some specified paths were not resolved, unable to cache
Explore other topics
Node.js & npmnpm, yarn, and pnpm failures in CI - solved. DockerBuild, run, compose, and registry errors - explained. Pythonpip, poetry, venv, and pytest failures - fixed. Java & JVMMaven, Gradle, and JVM failures in CI - resolved. GoGo build, module, and test failures - diagnosed. RustCargo and toolchain failures in CI - fixed.