GitHub Actions "Unable to resolve action" - Fix uses: Reference Errors
A uses: reference points at an action GitHub cannot find: the owner/repo path is wrong, the tag or SHA does not exist, or the action is private and the token has no access.
What this error means
A step fails immediately with "Unable to resolve action <ref>, repository not found" or "unable to find version". No action code runs because the reference cannot be downloaded.
Error: Unable to resolve action actions/checkout@v99, unable to find version v99
# or
Error: Unable to resolve action my-org/private-action@main, repository not foundDiagnose 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 non-existent ref
The owner/repo is misspelled, or the @ref points at a tag, branch, or SHA that does not exist on that action repository.
Private action without access
The default GITHUB_TOKEN cannot read a private action in another repository or org unless access is explicitly granted.
How to fix it
Pin to a real, existing ref
Use the correct owner/repo and a tag or commit SHA that exists. Pinning to a full SHA is the most reliable and secure form.
- uses: actions/checkout@v4
# or pin by commit SHA for supply-chain safety
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11Grant access to a private action
- Add a token with read access to the action repository, or check out that repo first.
- In org settings, allow the workflow repository to access the private action repository.
- Reference local actions with a relative path (./.github/actions/foo) when they live in the same repo.
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
- Pin actions to a tag or full commit SHA you have verified exists.
- Use Dependabot to keep action versions current and valid.
- Keep shared internal actions in a repo all consuming repos can read.