GitHub Actions "Cannot trigger workflow_dispatch - workflow not on default branch"

By Daniel Zoghalchali·Latchkey

The manual Run workflow UI and the workflow_dispatch trigger only become available once the workflow file declaring on: workflow_dispatch exists on the default branch. A dispatch-only feature branch will not show the button.

What this error means

The Run workflow button is absent, or an API dispatch fails because the workflow cannot be triggered.

Error: Cannot trigger a workflow_dispatch on a workflow that does not exist on the default branch.
The workflow file with on: workflow_dispatch must be present on the default branch.

Common causes

workflow_dispatch only on a feature branch

GitHub reads the dispatch trigger from the default branch; if it is not there, no dispatch is offered.

How to fix it

Add the dispatch trigger to the default branch

1. Merge the workflow (with on: workflow_dispatch) to the default branch.
2. The Run workflow button then appears and you can choose a ref to run on.

on:
  workflow_dispatch:
    inputs:
      env:
        type: choice
        options: [dev, prod]

How to prevent it

• Land dispatch triggers on the default branch first.
• Remember the trigger definition is read from the default branch, even if you run other refs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions