GitHub Actions "reusable workflow was not found"
Calling a reusable workflow requires the exact path under .github/workflows on a ref that exists, and the called file must declare on: workflow_call. A wrong path or ref makes it unresolvable.
What this error means
The caller run fails at startup with "reusable workflow was not found", naming the org/repo/.github/workflows/<file>@<ref> it tried to load.
Error: error parsing called workflow: reusable workflow was not found: org/repo/.github/workflows/build.yml@v1Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Wrong path or ref
The called workflow path under .github/workflows is misspelled, or the @ref does not exist on the target repo.
Called file lacks workflow_call
The target file does not declare on: workflow_call, so it is not callable.
How to fix it
Point at a valid callable workflow
- Use the full path under .github/workflows and a ref that exists.
- Confirm the called workflow has on: workflow_call.
- For private repos, ensure the caller can access the target.
jobs:
call:
uses: org/repo/.github/workflows/build.yml@mainCatch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Reference reusable workflows by exact path and an existing ref.
- Ensure called workflows declare on: workflow_call.
- Verify cross-repo access for private reusable workflows.