Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A local composite action in GitHub Actions cannot be found

ErrorA step with uses: ./some/path fails before any step of the action itself runs

Short 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.

  • Applies to GitHub Actions, GitHub-hosted ubuntu-24.04 runner
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/actions
  2. 2Match what you see, then jump to its fix

    1. 1The listing step fails with 'No such file or directory'The repository was not checked out before the local action runsFix
    2. 2The 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. 3The path was written relative to the workflow file, or the checkout used a path: inputThe path is resolved from the wrong placeFix

What does the error look like?

  • A step with uses: ./some/path fails before any step of the action itself runs
  • The 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/*.yml

2Fix

Run actions/checkout first in the same job, before any step with uses: ./...

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/hello-world-composite-action

3Verify

The local action step starts and prints its own log.

gh run view RUN_ID --log | grep -i composite

Confirmed by docs.github.com

Did this fix it?

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-action

3Verify

The step resolves the action and runs its steps.

gh run view RUN_ID

Confirmed by docs.github.com

Did this fix it?

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 -a

2Fix

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-action

3Verify

The action runs from a fresh checkout.

gh run rerun RUN_ID

Confirmed by docs.github.com

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.