Home / GitHub Actions / GitHub Actions Manual Workflow Trigger Failed

GitHub Actions

GitHub Actions Manual Workflow Trigger Failed

Fix GitHub Actions manual trigger failures from the UI, CLI, or API by checking `workflow_dispatch`, required inputs, ref selection, and workflow enablement.

Published: Jan 22, 202610 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

GitHub Actions manual workflow triggers allow developers to execute workflows on demand through the GitHub web interface, CLI, or API. This capability is essential for deployment workflows, maintenance tasks, emergency procedures, and development testing. Manual triggers are controlled by the workflow_dispatch event type, which must be explicitly declared in the workflow file.

When manual triggers fail, the error typically occurs before the workflow execution begins. GitHub's dispatch API validates the request against the workflow definition, checking for event type declaration, input validation, branch existence, and workflow enablement. Any mismatch results in an immediate rejection—often with HTTP 422 responses or input validation errors—without creating a workflow run.

Understanding the dispatch validation chain—from workflow file presence through trigger configuration to input schema matching—is essential for debugging manual trigger failures. The dispatch process differs significantly from automatic triggers like push or pull_request events, which automatically create runs based on repository events.

Symptoms

When GitHub Actions manual workflow triggers fail, you will observe these symptoms:

GitHub UI shows "This workflow cannot be run manually" or similar error
The "Run workflow" button is missing from the workflow page
gh workflow run returns HTTP 422 Unprocessable Entity
API dispatch requests fail immediately without creating runs
Manual triggers work from some branches but not others
Workflow previously worked but now fails after repository changes
Input validation errors show specific fields as invalid or missing

Common error messages from GitHub CLI:

``` gh workflow run deploy.yml gh: workflow 'deploy.yml' is not configured to be triggered by workflow_dispatch

gh workflow run deploy.yml -f version=1.0.0 gh: HTTP 422: Inputs validation failed Required input 'environment' not provided

gh workflow run deploy.yml --ref feature-branch gh: Workflow file '.github/workflows/deploy.yml' not found on ref 'feature-branch' ```

API error responses:

```json { "message": "workflow_dispatch webhook configuration for repository not found", "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event" }

{ "message": "Invalid request.\n\nworkflow file '.github/workflows/deploy.yml' does not exist on branch 'feature-branch'" } ```

GitHub UI states indicating dispatch failure:

``` Status: No workflow runs found Actions: This workflow has never been run

When clicking "Run workflow": "Unable to run workflow: This workflow does not define a workflow_dispatch trigger" ```

Common Causes

Several factors cause GitHub Actions manual workflow trigger failures:

1.**Workflow lacks workflow_dispatch declaration**: The workflow file does not include the workflow_dispatch trigger type. Without this declaration, GitHub considers the workflow non-manually-triggerable.
2.Workflow file missing on target ref: The dispatch targets a branch where the workflow file doesn't exist. This happens when workflows exist only on certain branches or after branch deletions.
3.Required inputs not provided: The workflow defines required inputs in its dispatch configuration, but the trigger request doesn't include those inputs or provides invalid values.
4.Workflow disabled: Repository administrators may disable specific workflows to prevent execution. Disabled workflows cannot be triggered manually or automatically.
5.Insufficient token permissions: The token used for dispatch (via API or CLI) lacks workflow write permissions for the repository.
6.Input type mismatch: The workflow defines boolean, number, or choice input types, but the dispatch provides string values that don't convert correctly.
7.Workflow file syntax errors: YAML syntax issues in the workflow file prevent GitHub from parsing the dispatch configuration.
8.Branch name case sensitivity: Branch names are case-sensitive; using wrong case in ref parameter causes GitHub to look for workflow on non-existent branch.

Step-by-Step Fix

Follow these steps to diagnose and resolve manual workflow trigger failures:

Step 1: Verify workflow_dispatch declaration

Check the workflow includes the dispatch trigger:

```bash # Get workflow file content gh api repos/:owner/:repo/contents/.github/workflows/deploy.yml --jq '.content' | base64 -d

# Or view locally cat .github/workflows/deploy.yml | grep -A5 "on:" ```

Required workflow dispatch configuration:

```yaml # Minimal declaration (no inputs) on: workflow_dispatch:

# With inputs on: workflow_dispatch: inputs: environment: description: 'Deployment environment' required: true type: choice options: - staging - production version: description: 'Version to deploy' required: true type: string ```

If declaration missing, add it:

yaml

on:
  workflow_dispatch:  # Add this line
  push:
    branches: [main]

Step 2: Verify workflow exists on target branch

Check the workflow file presence on the specific ref:

```bash # Check workflow file on specific branch gh api repos/:owner/:repo/contents/.github/workflows/deploy.yml?ref=main

# If file missing, returns 404 # HTTP 404: Not Found - workflow file does not exist

# List all workflows on branch gh api repos/:owner/:repo/actions/workflows?ref=main --jq '.workflows[].path'

# Check if branch exists gh api repos/:owner/:repo/branches/main --jq '.name' ```

If workflow exists on different branch:

```bash # Trigger from branch that has the workflow gh workflow run deploy.yml --ref main

# Or copy workflow file to target branch git checkout feature-branch git checkout main -- .github/workflows/deploy.yml git commit -m "Add deploy workflow" git push origin feature-branch ```

Step 3: Provide all required inputs

Identify and supply required inputs:

```bash # View workflow input schema gh api repos/:owner/:repo/actions/workflows/deploy.yml --jq '.inputs'

# Extract required inputs gh api repos/:owner/:repo/actions/workflows/deploy.yml --jq '.inputs | to_entries | .[] | select(.value.required == true) | .key'

# Provide all required inputs gh workflow run deploy.yml \ --ref main \ -f environment=staging \ -f version=1.0.0

# For boolean inputs, use -F gh workflow run deploy.yml \ -f environment=staging \ -F dry-run # Sets dry-run to true ```

Step 4: Check workflow enablement status

Verify the workflow is enabled:

```bash # Check workflow status gh api repos/:owner/:repo/actions/workflows/deploy.yml --jq '{state: .state, disabled_at: .disabled_at}'

# If state is "disabled_manually", enable it gh workflow enable deploy.yml

# Or via API gh api -X PUT repos/:owner/:repo/actions/workflows/deploy.yml/enable

# Check if now enabled gh workflow list --all | grep deploy ```

Step 5: Verify token permissions

Check the token has workflow permissions:

```bash # Check token scope for CLI gh auth status

# Required scopes: workflow (or repo for full access) # If missing, refresh authentication gh auth refresh -h github.com -s workflow

# Expected scopes include: repo, workflow ```

Step 6: Validate input types

Match input types exactly:

yaml

# Workflow defines these input types:
inputs:
  environment:
    type: choice
    options: [staging, production]
  replicas:
    type: number
  dry-run:
    type: boolean

```bash # Correct type passing: gh workflow run deploy.yml \ -f environment=production \ -f replicas=5 \ -F dry-run

# WRONG: String for number gh workflow run deploy.yml -f replicas="five" # Error: Value must be a number

# WRONG: String for boolean gh workflow run deploy.yml -f dry-run=yes # Error: Value must be true or false

# WRONG: Choice value not in options gh workflow run deploy.yml -f environment=prod # Error: must be one of ["staging", "production"] ```

Step 7: Check for workflow file syntax errors

Validate YAML syntax:

```bash # Validate YAML syntax locally python3 -c "import yaml; yaml.safe_load(open('.github/workflows/deploy.yml'))"

# Or use yq yq . .github/workflows/deploy.yml

# Common syntax errors: # - Missing quotes around special characters # - Incorrect indentation # - Duplicate keys # - Invalid YAML structures ```

Step 8: Test with minimal dispatch

Test basic functionality:

```bash # Create minimal test workflow cat > .github/workflows/test-manual.yml << 'EOF' name: Manual Test on: workflow_dispatch: jobs: test: runs-on: ubuntu-latest steps: - run: echo "Manual trigger works!" EOF

git add .github/workflows/test-manual.yml git commit -m "Add test workflow" git push

# Trigger minimal workflow gh workflow run test-manual.yml

# Check run was created gh run list --workflow=test-manual.yml --limit 1 ```

Verification

After fixing dispatch configuration, verify manual triggers work:

```bash # Trigger workflow with all required inputs gh workflow run deploy.yml \ --ref main \ -f environment=staging \ -f version=1.0.0 \ -F dry-run

# Verify run was created gh run list --workflow=deploy.yml --limit 1

# Expected output: ID STATUS NAME CREATED 12345678 queued deploy.yml 2 minutes ago

# Watch run execution gh run watch

# View run details gh run view --json status,conclusion,event # Expected: event: "workflow_dispatch"

# Check GitHub UI # Navigate to Actions > deploy.yml # Should show recent manual run ```

API verification:

```bash # Check workflow runs via API gh api repos/:owner/:repo/actions/runs?workflow_id=deploy.yml --jq '.workflow_runs[0] | {id, event, status}'

# Expected output: { "id": 12345678, "event": "workflow_dispatch", "status": "completed" } ```

Prevention

To prevent manual workflow trigger failures:

1.Document workflow inputs: Maintain clear documentation of required inputs and valid values.

markdown

## Manual Deployment Workflow
**Workflow:** deploy.yml
**Inputs:**
- `environment`: Required. Options: staging, production
- `version`: Required. Format: semver (e.g., 1.2.3)
- `dry-run`: Optional. Boolean.

1.Include dispatch in workflow templates: Ensure reusable workflow templates include workflow_dispatch.

yaml

on:
  workflow_dispatch:  # Always include for operational workflows
  push:
    branches: [main]

1.Test dispatch after workflow changes: Verify manual triggers work after any workflow modification.

bash

# Post-change verification
gh workflow run deploy.yml -f environment=staging -f version=test
gh run watch

1.Use defaults for optional inputs: Provide sensible defaults for optional parameters.

yaml

inputs:
  replicas:
    description: 'Number of replicas'
    required: false
    default: 3
    type: number

1.Create dispatch helper scripts: Build scripts that provide correct inputs consistently.

bash

#!/bin/bash
# deploy.sh - Manual deployment script
gh workflow run deploy.yml \
  --ref main \
  -f environment="${1:-staging}" \
  -f version="$2" \
  -F dry-run="${3:-false}"
gh run watch

1.Monitor workflow dispatch failures: Track dispatch failures in operational metrics.

yaml

# Alert workflow for dispatch monitoring
name: Monitor Manual Dispatches
on:
  workflow_dispatch:
    inputs:
      check_workflow:
        required: true
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - run: gh workflow enable ${{ inputs.check_workflow }}

1.Keep workflows consistent across branches: Avoid branch drift for critical operational workflows.

bash

# Sync workflow to all deployment branches
for branch in main staging production; do
  git checkout $branch
  git checkout main -- .github/workflows/deploy.yml
  git commit -m "Sync deploy workflow"
  git push origin $branch
done

[WordPress troubleshooting: Fix IAM Access Denied 403 - Complete Tro](fix-iam-access-denied-403)
[GitHub Actions Artifact Expired or 403 Download Failed](github-actions-artifact-expired-403-download-failed)
[Fix Github Actions Artifact Upload Failed File Too Large 5gb Limit Issue in GitHub Actions](github-actions-artifact-upload-failed-file-too-large-5gb-limit)
[Fix Github Actions Aws S3 Deploy Credentials Expired Rotate Issue in GitHub Actions](github-actions-aws-s3-deploy-credentials-expired-rotate)
[Fix Github Actions Cache Evicted Manually Workflow Fails Download Issue in GitHub Actions](github-actions-cache-evicted-manually-workflow-fails-download)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

GitHub Actions Manual Workflow Trigger Failed GitHub Actions Manual Workflow Trigger Failed GitHub Actions GitHub Actions Manual Workflow Trigger Failed troubleshooting GitHub Actions Manual Workflow Trigger Failed fix Fix GitHub Actions manual trigger failures from the UI, CLI, or API by checking `workflow_dispatch`, required inputs, ref selection, and workflow enablement GitHub Actions Fix GitHub Actions manual trigger failures from the UI, CLI, or API by checking `workflow_dispatch`, required inputs, ref selection, and workflow enablement

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

GitHub Actions Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this github-actions-errors troubleshooting guide applies to my situation?

This guide is designed for github-actions-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these github-actions-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of github-actions-errors issue?

Most github-actions-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this github-actions-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for github-actions-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Jan 22, 2026

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

GitHub Actions Manual Workflow Trigger Failed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Verify workflow_dispatch declaration

Step 2: Verify workflow exists on target branch

Step 3: Provide all required inputs

Step 4: Check workflow enablement status

Step 5: Verify token permissions

Step 6: Validate input types

Step 7: Check for workflow file syntax errors

Step 8: Test with minimal dispatch

Verification

Prevention

Related Articles

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

GitHub Actions Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

GitHub Actions Manual Workflow Trigger Failed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Verify workflow_dispatch declaration

Step 2: Verify workflow exists on target branch

Step 3: Provide all required inputs

Step 4: Check workflow enablement status

Step 5: Verify token permissions

Step 6: Validate input types

Step 7: Check for workflow file syntax errors

Step 8: Test with minimal dispatch

Verification

Prevention

Related Articles

People also search for

Share this guide

More GitHub Actions Troubleshooting Guides

Browse Guides from Other Categories

GitHub Actions Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading