GitHub Actions "Invalid workflow file ... called workflow ... not found" in CI

GitHub resolved your uses: value and looked for the called workflow at that path and ref, but no file exists there. The path is wrong, the ref does not contain the file, or the file was never merged to that ref.

What this error means

The caller fails immediately with "Invalid workflow file" and "the workflow ... was not found". No job in the reusable workflow ever runs.

GitHub Actions

Invalid workflow file: .github/workflows/ci.yml#L10
The workflow "octo-org/shared/.github/workflows/deploy.yml@v1" was not found.
Did you mean to reference a different ref or path?

Common causes

The path does not exist at that ref

The file might live at a different path, or exist on main but not on the tag v1 you pinned. GitHub reads the called workflow from the ref you named, not from HEAD.

The file was renamed or not yet released

You renamed deploy.yml or added it after cutting v1, so the tag you call still lacks the file.

How to fix it

Confirm the file exists at the exact ref

Browse the called repo at that tag/branch/SHA and confirm the path resolves.
Correct the path or point at a ref that actually contains the file.
Re-run the caller so it can locate the called workflow.

.github/workflows/ci.yml

jobs:
  deploy:
    # v1 must contain this exact path
    uses: octo-org/shared/.github/workflows/deploy.yml@v1

Move a floating tag to a commit that has the file

If you added the workflow after cutting the tag, re-point the tag (or call a branch/SHA that includes it) so the ref contains the file.

Terminal

git tag -f v1 <commit-with-deploy.yml>
git push origin v1 --force

How to prevent it

Cut a fresh tag after adding or renaming a reusable workflow.
Reference reusable workflows by full SHA so the file is guaranteed present.
Keep called-workflow paths stable once other repos depend on them.