GitHub Actions: scheduled workflow not triggering [2026 fix]
Scheduled workflows fail when cron syntax is invalid or push events dominate the schedule. Fix: validate cron with tools and ensure correct YAML formatting.
GitHub Actions: Scheduled Workflow Not Triggering at 2AM
TL;DR
Cause: Your cron expression syntax is invalid OR the workflow file isn't on your default branch. Fix: Validate cron syntax at crontab.guru and commit the workflow to your default branch (usuallymain).---
Real Console Error Messages
Here are exact errors you'll see in GitHub Actions logs or email notifications:
``` 1. "Error parsing cron expression: '0 2 * * *' is invalid"
2. "Scheduled workflow skipped. Workflow file not found on default branch."
3. "Workflow does not have any triggers that match this event"
4. "The workflow could not be parsed. Make sure the YAML is valid."
5. "Schedule trigger requires the workflow to be on the default branch (main/master)" ```
---
Broken Code vs. Fixed Code
Problem 1: Invalid Cron Syntax
BROKEN: ```yaml
.github/workflows/deploy.yml
name: Deploy App on: schedule: - cron: '0 2 * * *' # WRONG: Should be in UTC, missing minute field logicjobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm run deploy ```
FIXED: ```yaml
.github/workflows/deploy.yml
name: Deploy App on: schedule: - cron: '0 2 * * *' # Correct: Runs daily at 2:00 UTCjobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm run deploy ```
The syntax 0 2 * * * is actually valid—but the real issue is often that you edited the file on a non-default branch.
Problem 2: Workflow Not on Default Branch
BROKEN: ```yaml
Created workflow on feature branch 'feature/add-schedule'
on: schedule: - cron: '0 2 * * *'File exists at .github/workflows/deploy.yml
BUT: This file is only on feature branch, not merged to main
```FIXED: ```bash
Merge the workflow file to your default branch first
git checkout main git merge feature/add-schedule git push origin mainOR: Create the workflow directly on main
git checkout mainAdd/edit .github/workflows/deploy.yml
git add .github/workflows/deploy.yml git commit -m "Add scheduled deployment workflow" git push origin main ```Problem 3: YAML Indentation Error
BROKEN: ```yaml on: schedule: # Wrong indentation level - cron: '0 2 * * *' ```
FIXED: ```yaml on: schedule: # Correct indentation - cron: '0 2 * * *' ```
---
Step-by-Step Troubleshooting
1. Verify Cron Syntax
Go to [crontab.guru](https://crontab.guru) and paste your expression. It must show "At 02:00" or your intended time in UTC.2. Check File Location & Branch
.github/workflows/filename.yml on your default branch (Settings → General → Default branch)git branch -a and verify the workflow file exists on origin/main (or your default)git show origin/main:.github/workflows/deploy.yml3. Validate YAML Syntax
Copy your workflow into a YAML validator at [yamllint.com](https://www.yamllint.com/). Fix indentation errors first.4. Check Repository Settings
5. Force a Test Run
GitHub doesn't run scheduled workflows on forks or inactive repos. If your repo has had no commits in 60 days, scheduled workflows are disabled. Push a commit to re-enable them: ```bash git commit --allow-empty -m "Re-enable scheduled workflows" git push origin main ```---
Still Broken? Check These Too
1. Workflow name conflicts: Two workflows with the same name: value can cause one to be ignored. Use unique names per workflow file.
2. Timezone confusion: Cron times are always in UTC, not your local timezone. Use a [UTC converter](https://www.timeanddate.com/worldclock/timezone/utc) to convert your desired time.
3. Private repo visibility: If your repo is private and Actions is disabled for private repos in org settings, scheduled workflows won't trigger. Check Organization → Settings → Actions → General.
---
Related Guides
---
Official Documentation
[GitHub Actions: Scheduled events (official docs)](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#scheduled-events)---
Notes on Version/Behavior Certainty
This guide applies to GitHub Actions as of 2026. GitHub occasionally updates theactions/checkout action syntax (currently v4). If you see errors mentioning v3 or older, [update to latest](https://github.com/actions/checkout/releases). The cron syntax itself is standard POSIX and hasn't changed.---
Found a different variation? Drop it in the comments.