Introduction

Manual workflow runs fail before execution when GitHub cannot create the dispatch event. That usually means the workflow does not declare workflow_dispatch, the selected ref does not contain the expected workflow definition, or the caller did not supply required inputs. The error often looks like a permissions or API problem even though the real issue is workflow configuration.

Symptoms

  • The GitHub UI refuses to start a manual run
  • gh workflow run returns HTTP 422 or input validation errors
  • API-triggered workflow dispatch requests fail immediately
  • The workflow exists in one branch but cannot be manually triggered from another

Common Causes

  • The workflow file does not include workflow_dispatch
  • Required manual inputs were omitted or invalid
  • The selected branch or ref does not contain the workflow file
  • The workflow is disabled or the caller token cannot dispatch it

Step-by-Step Fix

  1. 1.**Confirm the workflow declares workflow_dispatch**
  2. 2.Manual runs will never work without an explicit dispatch trigger in the target workflow.
yaml
on:
  workflow_dispatch:
  1. 1.Check required inputs and pass them explicitly
  2. 2.If the workflow defines required inputs, the UI, CLI, or API caller must provide valid values.
bash
gh workflow run deploy.yml --ref main -f environment=staging
  1. 1.Verify the workflow exists on the selected ref
  2. 2.Manual dispatch targets the workflow file as it exists on the chosen branch or ref, not necessarily the default branch version you last reviewed.
  3. 3.Make sure the workflow is enabled
  4. 4.A disabled workflow or insufficient token scope can block manual dispatch even when the YAML itself is valid.
bash
gh workflow enable deploy.yml

Prevention

  • Include workflow_dispatch on workflows that operators need to run manually
  • Keep required input names simple and well documented
  • Test manual triggers with the same ref and input set used in operations
  • Avoid branch-specific workflow drift for critical deploy or recovery pipelines