Maaz Zindani

Loading the index…

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

GitHub Actions cannot find or parse the reusable workflow you call

Errorerror parsing called workflow

Short answer

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. A wrong path, a subfolder, a bad ref format or a missing trigger all make GitHub fail to find or parse the called workflow.

  • Applies to GitHub Actions
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every uses: line that points at a workflow and compare it, character by character, with the real file path in the called repository.

    grep -n "uses:.*\.github/workflows" .github/workflows/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1'workflow was not found' for a file you believe exists.The path or filename is wrong, or the file is in a subfolderFix
    2. 2The path is right but the error remains for a repository other than the caller's.The ref after @ is missing, misspelled or written as refs/heads/...Fix
    3. 3The called file is in the same repository as the caller.A same-repository call is written with a ref, or in the wrong placeFix
    4. 4The file is found but the caller reports a parsing problem.The called file does not declare workflow_callFix

What does the error look like?

  • error parsing called workflow
  • workflow was not found

Cause 1 of 4

The path or filename is wrong, or the file is in a subfolder

1Check

Reusable workflows must sit in the .github/workflows directory, and subdirectories of workflows are not supported. The path ends with the file name, including .yml or .yaml.

# open this page in a browser and read the file names:
      # https://github.com/OWNER/REPO/tree/REF/.github/workflows

2Fix

Move the file directly into .github/workflows and use the exact name in uses.

jobs:
  call:
    uses: OWNER/REPO/.github/workflows/build.yml@v1

3Verify

Re-run the caller; the job expands into the called workflow's jobs.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

Cause 2 of 4

The ref after @ is missing, misspelled or written as refs/heads/...

1Check

For another repository the form is {owner}/{repo}/.github/workflows/{filename}@{ref}. The ref can be a SHA, a release tag or a branch name. Prefixes such as refs/heads and refs/tags are not allowed, and contexts or expressions cannot be used in uses.

# open https://github.com/OWNER/REPO/tags and confirm the tag or branch exists

2Fix

Use a plain branch name, tag or full commit SHA. A SHA is the safest choice.

uses: OWNER/REPO/.github/workflows/build.yml@main

3Verify

The run starts and shows the called jobs.

gh run list --limit 3

Confirmed by docs.github.com

Did this fix it?

Cause 3 of 4

A same-repository call is written with a ref, or in the wrong place

1Check

Same-repository calls use ./.github/workflows/{filename}, which takes the called workflow from the same commit as the caller. The call must be a job-level uses, not inside steps.

grep -n -B2 "uses: ./.github/workflows" .github/workflows/*.yml

2Fix

Drop the @ref, and put uses directly under the job.

jobs:
  call:
    uses: ./.github/workflows/build.yml

3Verify

The called jobs appear under the caller in the run graph.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

Cause 4 of 4

The called file does not declare workflow_call

1Check

For a workflow to be reusable, the values for on must include workflow_call.

grep -n -A3 "^on:" .github/workflows/build.yml

2Fix

Add the trigger to the called workflow, with any inputs and secrets it needs.

on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true

3Verify

Commit the change to the ref that the caller uses, then re-run the caller.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Pin the called workflow to a release tag or commit SHA and update it on purpose.
  • Keep reusable workflows directly in .github/workflows with clear names.
  • Change the called workflow on the ref the callers use; a fix on another branch is invisible to them.

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

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

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.