GitHub Actions "Workflow does not exist" (workflow_dispatch on non-default branch)

By Daniel Zoghalchali·Latchkey

The manual run button and the dispatch API only appear after a workflow with the workflow_dispatch trigger has merged to the repository default branch. On a feature branch only, it will not show.

What this error means

A manual dispatch fails or the workflow is missing from the Run workflow list, even though the file exists on a feature branch.

HTTP 422: Workflow does not exist.

Common causes

Workflow not on default branch

workflow_dispatch availability is determined by the file on the default branch.

Dispatching the wrong ref

You can run it on any ref once registered, but registration itself comes from the default branch.

How to fix it

Merge the workflow to the default branch

1. Ensure the workflow with on: workflow_dispatch is merged to the default branch at least once.
2. Then dispatch and choose the target ref in the UI or API.
3. Use gh workflow run with --ref to target a branch after registration.

gh workflow run deploy.yml --ref feature/x

How to prevent it

• Land new dispatchable workflows on the default branch before relying on the run button.
• Document that the trigger registers from the default branch.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions