GitHub Actions "error parsing called workflow ... invalid value ... uses" in CI

By Daniel Zoghalchali·Latchkey

A job-level uses: that calls a reusable workflow must be written as owner/repo/.github/workflows/file.yml@ref (or ./.github/workflows/file.yml for a local one). GitHub rejects any other shape while parsing the caller.

What this error means

The run fails at parse time with "error parsing called workflow" and "invalid value" pointing at the job's uses: line. The caller never starts the called workflow.

error parsing called workflow
".github/workflows/ci.yml"
-> "deploy" (Line: 12, Col: 11): invalid value. Expected format {owner}/{repo}/.github/workflows/{filename}@{ref}

Common causes

The uses value is missing the @ref

A remote reusable-workflow call requires a git ref after @ (branch, tag, or full SHA). octo/repo/.github/workflows/deploy.yml with no @main is rejected.

A local call is not written with a leading ./

A same-repo reusable workflow must be ./.github/workflows/deploy.yml with no @ref. Writing just .github/workflows/deploy.yml fails the format check.

How to fix it

Use the exact remote call format

1. For another repo, write owner/repo, the full path under .github/workflows, then @ref.
2. Pick a ref that exists: a branch, a tag, or a full commit SHA.
3. Re-run so the caller can resolve and parse the called workflow.

jobs:
  deploy:
    uses: octo-org/shared/.github/workflows/deploy.yml@v1

Use a leading ./ for a local workflow

A reusable workflow in the same repository is referenced by path relative to the repo root, with a leading ./ and no @ref.

jobs:
  deploy:
    uses: ./.github/workflows/deploy.yml

How to prevent it

• Remember: remote calls need owner/repo/path@ref, local calls need ./path with no ref.
• Pin remote reusable workflows to a tag or full SHA, not a moving branch.
• Validate workflow YAML in a pre-push hook so format errors surface before CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions