GitHub Actions "The requested workflow was not found at ref"

Workflow dispatch and reusable-workflow references resolve the workflow file as it exists on a specific ref. If the file is absent on that ref, GitHub returns not found even when it exists on another branch.

What this error means

A dispatch or call fails with the requested workflow not being found at the specified ref.

github-actions

Error: The requested workflow was not found at ref 'refs/heads/feature-x'.
Ensure the workflow file exists on that ref.

Common causes

Workflow file missing on the target ref

The file exists on another branch but not on the ref being dispatched/called.

Renamed or moved workflow file

The path changed and the dispatch still references the old name.

How to fix it

Reference an existing ref and path

Confirm the workflow file exists at the exact path on the target ref.
For workflow_dispatch via API, ensure the ref input points to a branch that contains the file.
Merge the workflow to the target branch if needed.

How to prevent it

Keep dispatchable workflows on the branches you dispatch from.
Update references when renaming or moving workflow files.

Related guides

GitHub Actions "Cannot trigger workflow_dispatch - workflow not on default branch"Fix a missing Run workflow button or dispatch error caused by the workflow_dispatch trigger not existing on t… GitHub Actions "reusable workflow was not found"Fix GitHub Actions "reusable workflow was not found" - a uses: to a called workflow points at a path or ref t… GitHub Actions "Skipping this check because the workflow file is invalid on this ref"Fix a required check that is silently skipped because the workflow file is invalid on the PR base or head ref.