GitHub Actions Tutorial — Common Errors

Common Errors

These are the errors you’ll encounter most often in GitHub Actions — with exact error messages, causes, and fixes.

---

YAML Syntax Errors

Error:

Invalid workflow file: .github/workflows/ci.yml

Causes:

• Wrong indentation (YAML uses spaces, not tabs)
• Missing colons after keys
• Unclosed strings or arrays

Fix: Use a YAML linter or the GitHub Actions workflow editor.

---

Action Not Found

Error:

Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under
'/home/runner/work/_actions/my-org/my-action/v1'

Causes:

• Action repository doesn’t exist or is private
• Version tag doesn’t exist
• action.yml is in a subdirectory

Fix:

# Check the action exists and tag is correct
- uses: actions/checkout@v4        # ✅
- uses: actions/checkout@v99       # ❌ tag doesn't exist
- uses: private-org/action@v1      # ❌ if repo is private (no access)

---

Permission Denied

Error:

Error: Resource not accessible by integration

Causes:

• GITHUB_TOKEN doesn’t have required permissions
• Default permissions are read-only (for forked repos)

Fix:

permissions:
  contents: read
  pull-requests: write     # add what you need
  issues: write
  packages: write

---

Secret Not Found

Error:

Error: Input required and not supplied: token

Causes:

• Secret name is misspelled
• Secret is in a different environment
• Secret was deleted

Fix:

# Check secret names match exactly (case-sensitive)
- uses: my-action@v1
  with:
    token: ${{ secrets.MY_TOKEN }}    # must match Settings → Secrets name

---

Checkout Fails

Error:

fatal: could not read Username for 'https://github.com': terminal prompts disabled

Causes:

• Checking out a private repository
• Submodules require authentication

Fix:

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.PAT_TOKEN }}    # PAT with repo scope
    submodules: recursive               # if submodules are needed

---

Job Timeout

Error:

The job running on runner GitHub Actions 2 has exceeded the maximum
execution time of 360 minutes.

Causes:

• Infinite loop in script
• Hanging network request
• Waiting for user input

Fix:

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30          # set a reasonable limit

    steps:
      - run: npm test
        timeout-minutes: 10      # per-step timeout

---

Cache Miss

Error (not really an error — just slow):

Cache not found for input keys: ...

Causes:

• Cache key doesn’t match (different lock file hash)
• Cache expired (7 days for unused caches)
• Cache size exceeded (10 GB per repository)

Fix:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

restore-keys provides fallback partial matches.

---

Artifact Upload/Download Issues

Error:

Error: Artifact not found for the name: my-artifact

Causes:

• Artifact name mismatch between upload and download
• Artifact expired (default: 90 days)
• Upload step failed silently

Fix:

# Upload
- uses: actions/upload-artifact@v4
  with:
    name: build-output          # exact name
    path: dist/

# Download (in a different job)
- uses: actions/download-artifact@v4
  with:
    name: build-output          # must match exactly

---

Common Mistakes Summary

Error	Most Likely Cause	Quick Fix
Invalid workflow file	YAML indentation	Use spaces, not tabs
Action not found	Wrong version tag	Verify the tag exists
Resource not accessible	Missing permissions	Add permissions: block
Secret not supplied	Misspelled name	Check Settings → Secrets
Checkout fails	Private repo	Use PAT token
Job timeout	Infinite loop or hang	Add timeout-minutes:
Cache miss	Lock file changed	Add restore-keys:
Artifact not found	Name mismatch	Match names exactly

---

← Previous: Debug Logging

Next: Act (Local Testing) →