Unable to Resolve Action: Unable to Find Version
Last updated
Unable to resolve action means GitHub could not download the action your uses: line points at, so the job failed before running any step. Either the action reference (owner, repository, path or version) does not exist, or the workflow is not allowed to see it. This page covers both.
The exact message
Error: Unable to resolve action `actions/checkout@v9`, unable to find version `v9`
Error: Unable to resolve action `some-org/some-action@v1`, repository not found
Error: Unable to resolve action `owner/repo@main`, unable to find version `main`
Cause 1: the version does not exist
The tag, branch or commit after @ is not in that repository. Typical reasons are a typo, a major tag that the author never published (v3 when only v3.1.0 exists), or a tag that was deleted or moved. Check the repository's tags and releases on GitHub, or list them:
git ls-remote --tags https://github.com/actions/checkout | tail
Then pin to something that exists:
- uses: actions/checkout@v4
# or, safer, a full commit SHA with the version in a comment:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
Cause 2: the repository was renamed, moved or deleted
repository not found for an action that used to work means the owner renamed it, archived and removed it, or made it private. Search for its new location, or replace it with another action or a plain run step.
Cause 3: the action is in a private repository you cannot access
An action in a private repository can only be used by workflows that are allowed to see it. In the action repository go to Settings, Actions, General, and under "Access" choose to allow access from other repositories in your organisation (or user account). A workflow in a different organisation cannot use it this way: publish the action publicly, or copy it into the repository that uses it.
Cause 4: your organisation restricts which actions can run
If the organisation or repository policy allows only certain actions, a blocked action fails to resolve or is rejected with a message about the action not being allowed. Under Settings, Actions, General, "Actions permissions" shows the policy. Ask an organisation owner to add the action to the allow list, or use one that is already allowed.
Cause 5: a local action without a checkout
For a local action such as uses: ./.github/actions/setup, the code must be on the runner first. Add actions/checkout before it. Without it the error is usually "Can't find 'action.yml'", not this one, but the fix is the same.
Cause 6: wrong path for an action in a subdirectory
For actions in a subfolder the form is owner/repo/path@ref. A missing path or a wrong folder name fails to resolve.
- uses: github/codeql-action/init@v3
Cause 7: a reusable workflow reference
For uses: org/repo/.github/workflows/build.yml@main, the path must end in the workflow file name, the file must be on that ref, and the calling workflow must be allowed to access it (same access rules as private actions).
How to prevent it
- Pin actions to a full commit SHA, with a comment for the version, and let Dependabot update them. See Dependabot setup.
- Check that a tag exists before you reference it.
- Fork or vendor third-party actions you depend on for important pipelines.
- Review the allow-list when you add a new action, not when the build breaks.
FAQ
Is this a GitHub outage?
Almost never. If many unrelated workflows fail to download actions at once, check the GitHub status page.
Why does @v4 work for one action but @v1 fails for another?
Each repository chooses its own tags. Not every action publishes moving major tags such as v1.
Can I use a branch name?
Yes, @main works if the branch exists, but a moving branch can change under you. A SHA is safer.
How do I find which action failed?
The message names it in backticks. The first failing line in the "Set up job" step shows the exact owner/repo@ref.
Related
- Cache Service Responded With 429: FixFix "Failed to restore: Cache service responded with 429" in GitHub Actions: too many cache requests. Upgrade actions/cache, restore once, save once.
- fatal: could not read Username for github.com: FixFix "fatal: could not read Username for 'https://github.com'" in GitHub Actions: private repos, submodules and git dependencies need a token.
- Invalid Workflow File: YAML Syntax Error FixFix "Invalid workflow file" and "You have an error in your yaml syntax" in GitHub Actions: indentation, unexpected value, bad expressions, with actionlint.
- JavaScript Heap Out of Memory in GitHub Actions: FixFix "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory" and npm ENOMEM in GitHub Actions with NODE_OPTIONS.