A local composite action in GitHub Actions cannot be found
A step with uses: ./some/path fails before any step of the action itself runsShort answer
A local action is read from the checked-out repository. The step fails when the job has not run actions/checkout yet, when uses points at a file or a wrong folder instead of the directory that contains action.yml, or when the path is not relative to the repository root.
Fix it fast
1Find out which cause you have
Add a listing step before the failing one. It shows what the runner has in the workspace and whether your action folder is really there.
- run: ls -R .github/actions2Match what you see, then jump to its fix
- 1
The listing step fails with 'No such file or directory'The repository was not checked out before the local action runsFix - 2
The folder exists in the listing, but action.yml is missing from it, or uses ends in /action.ymluses points at the file, or at a folder without action.yml in itFix - 3
The path was written relative to the workflow file, or the checkout used a path: inputThe path is resolved from the wrong placeFix
- 1
What does the error look like?
A step with uses: ./some/path fails before any step of the action itself runsThe action folder is in the repository but the runner reports that its action.yml cannot be found
Cause 1 of 3
The repository was not checked out before the local action runs
1Check
A runner starts with an empty workspace. A local path in uses is only found after actions/checkout has put the repository there.
grep -n -B2 -A6 "checkout" .github/workflows/*.yml2Fix
Run actions/checkout first in the same job, before any step with uses: ./...
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/hello-world-composite-action3Verify
The local action step starts and prints its own log.
gh run view RUN_ID --log | grep -i compositeConfirmed by docs.github.com
Cause 2 of 3
uses points at the file, or at a folder without action.yml in it
1Check
uses has to name the directory that contains the action's metadata file, not the file itself.
find .github/actions -name "action.y*ml"2Fix
Make uses end at the folder, and keep the metadata file inside it with the name action.yml.
# layout
.github/actions/hello-world-composite-action/action.yml
# workflow
- uses: ./.github/actions/hello-world-composite-action3Verify
The step resolves the action and runs its steps.
gh run view RUN_IDConfirmed by docs.github.com
Cause 3 of 3
The path is resolved from the wrong place
1Check
A local path is resolved against the runner's workspace, which is the repository root after checkout. It is not relative to the workflow file.
pwd && ls -a2Fix
Write the path from the repository root. If the checkout step used a different path: input, include that folder in the path.
- uses: actions/checkout@v4
- uses: ./.github/actions/hello-world-composite-action3Verify
The action runs from a fresh checkout.
gh run rerun RUN_IDConfirmed by docs.github.com
How do I stop it coming back?
- Keep each action in its own folder with its action.yml inside.
- Run actions/checkout as the first step of any job that uses a local action.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
GitHub Actions cannot find or parse the reusable workflow you call
workflow was not found
A caller job's uses: value must point at a real workflow file in .github/workflows, directly inside that folder, at a ref that exists, and the called file must declare on: workflow_call.
4 causes, each with a fixServers
A GitHub Actions workflow builds the Docker image but cannot push it
The push step fails right after the login step
Four things stop a push from GitHub Actions: build-push-action does not push unless push is true, the Docker Hub login used a password instead of an access token, the workflow token lacks packages write for ghcr.io, or the run comes from a fork, where the token is read-only.
4 causes, each with a fixServers
A GitHub Actions step with shell: pwsh or powershell fails on Linux
shell: powershell on a Linux runner
GitHub starts a step with the shell name you give.
3 causes, each with a fixServers
Make a GitHub Actions step run after a failure, and keep the job failed
The job is green even though a step failed (continue-on-error)
A step with no if: condition gets success() by default, so it is skipped once any earlier step fails.
3 causes, each with a fixServers
A self-hosted GitHub Actions runner goes offline or stops by itself
Runner status in Settings > Actions > Runners shows Offline
GitHub marks a runner Offline when the machine is down, the runner application is not running, or it cannot reach GitHub.
3 causes, each with a fixServers
GitHub Actions step fails writing to GITHUB_OUTPUT
Error: Invalid format '...'
The runner reads GITHUB_OUTPUT line by line, and every entry must be name=value or a name<<DELIMITER block.
3 causes, each with a fix