GitHub Actions "Cannot trigger workflow_dispatch - workflow not on default branch"
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.Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
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
- Merge the workflow (with on: workflow_dispatch) to the default branch.
- 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]Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow 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.