GitHub Actions "This run likely failed because of ... reusable workflow"

A caller run fails not because of its own steps but because the reusable workflow it calls is invalid or unreachable. GitHub points back at the called workflow as the likely cause.

What this error means

The caller workflow fails very early with a message that the run likely failed because of an invalid reusable workflow, naming the called file or ref rather than a step.

This run likely failed because of a workflow file issue.
.github/workflows/build.yml@v2: the reusable workflow could not be validated

Common causes

Called workflow is invalid

A syntax error, missing on.workflow_call, or an undeclared required input in the called file makes the whole call fail before any job runs.

Bad ref or no access

A uses: that points at a tag/SHA that does not exist, or a called workflow in a repo the token cannot read, fails validation in the caller.

How to fix it

Validate the called workflow directly

Lint the called file and confirm it declares on.workflow_call with its inputs and secrets.

# build.yml (called)
on:
  workflow_call:
    inputs:
      target: { required: true, type: string }
jobs:
  build:
    runs-on: ubuntu-latest
    steps: [{ run: make ${{ inputs.target }} }]

Fix the reference and access

1. Use a uses: ref (tag or SHA) that exists on the called workflow repo.
2. Grant the workflow access to a called workflow in another repo.
3. Run actionlint on the called file to surface its own errors.

How to prevent it

• Lint reusable workflows independently, not just callers.
• Pin called workflows to refs you have verified exist.
• Declare all required inputs/secrets in on.workflow_call.

Related guides