Introduction

workflow_dispatch inputs are schema-validated before the workflow starts. If the caller omits a required input, sends the wrong choice value, or uses the wrong type, GitHub rejects the dispatch request and no run is created. This is why manual triggers can fail even though the workflow file itself is syntactically valid.

Symptoms

  • GitHub or gh workflow run reports that an input is missing
  • API-triggered dispatch returns HTTP 422
  • Choice inputs reject values that look similar but are not exact matches
  • A workflow worked before input definitions changed

Common Causes

  • Required inputs are not supplied
  • The caller sends a value outside the declared options set
  • Boolean, number, or string expectations do not match the payload sent by the caller
  • The workflow input definition changed, but the triggering script was not updated

Step-by-Step Fix

  1. 1.Inspect the workflow input schema
  2. 2.Start with the live workflow_dispatch definition on the exact branch being triggered.
yaml
on:
  workflow_dispatch:
    inputs:
      environment:
        required: true
        type: choice
        options:
          - staging
          - production
  1. 1.Pass every required input explicitly
  2. 2.Do not assume defaults exist unless they are declared in the workflow.
bash
gh workflow run deploy.yml --ref main -f environment=staging
  1. 1.Match choice values exactly
  2. 2.If the workflow says production, then prod is invalid even if humans treat them as the same environment.
  3. 3.Retest the API or CLI caller after workflow input changes
  4. 4.Many failures come from helper scripts that still send an older payload shape.

Prevention

  • Keep workflow_dispatch input names stable once operators or scripts depend on them
  • Use choice inputs for constrained values to make valid options explicit
  • Add defaults for optional fields where sensible
  • Update CLI and API trigger scripts whenever workflow input schemas change