GitHub Actions "The requested workflow was not found at ref"
Workflow dispatch and reusable-workflow references resolve the workflow file as it exists on a specific ref. If the file is absent on that ref, GitHub returns not found even when it exists on another branch.
What this error means
A dispatch or call fails with the requested workflow not being found at the specified ref.
Error: The requested workflow was not found at ref 'refs/heads/feature-x'.
Ensure the workflow file exists on that ref.Diagnose 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
Workflow file missing on the target ref
The file exists on another branch but not on the ref being dispatched/called.
Renamed or moved workflow file
The path changed and the dispatch still references the old name.
How to fix it
Reference an existing ref and path
- Confirm the workflow file exists at the exact path on the target ref.
- For workflow_dispatch via API, ensure the ref input points to a branch that contains the file.
- Merge the workflow to the target branch if needed.
Catch 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
- Keep dispatchable workflows on the branches you dispatch from.
- Update references when renaming or moving workflow files.