---
title: "Common GitHub Actions Errors and Solutions"
description: "This reference lists common errors encountered when working with GitHub Actions and how to fix them."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/common-errors-1
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:18:34.856Z
license: CC-BY-4.0
attribution: "Common GitHub Actions Errors and Solutions — Claudary (https://claudary.paisolsolutions.com/skills/common-errors-1)"
---

# Common GitHub Actions Errors and Solutions
This reference lists common errors encountered when working with GitHub Actions and how to fix them.

## Overview

# Common GitHub Actions Errors and Solutions

This reference lists common errors encountered when working with GitHub Actions and how to fix them.

## Syntax Errors

### 1. Invalid YAML Syntax

**Error:**
```
Error: Unable to process file command 'workflow' successfully.
```

**Common Causes:**
- Incorrect indentation (YAML is whitespace-sensitive)
- Missing colons
- Unquoted strings containing special characters
- Tabs instead of spaces

**Fix:**
```yaml
# Bad
name:My Workflow
jobs:
build:
  runs-on: ubuntu-latest

# Good
name: My Workflow
jobs:
  build:
    runs-on: ubuntu-latest
```

### 2. Missing Required Fields

**Error:**
```
Required property is missing: name
```

**Fix:**
```yaml
# Every workflow needs a name
name: CI Pipeline

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
```

### 3. Invalid Workflow Triggers

**Error:**
```
The workflow is not valid. Unexpected value 'on'
```

**Fix:**
```yaml
# Bad - wrong event name
on:
  pull-request:  # Should be pull_request

# Good
on:
  pull_request:
  push:
```

## Expression Errors

### 1. Incorrect Expression Syntax

**Error:**
```
Unrecognized named-value: 'github'. Located at position 1 within expression: github.ref
```

**Fix:**
```yaml
# Bad - missing ${{ }}
if: github.ref == 'refs/heads/main'

# Good
if: ${{ github.ref == 'refs/heads/main' }}

# Even better (GitHub Actions auto-evaluates if conditions)
if: github.ref == 'refs/heads/main'
```

### 2. Type Mismatches

**Error:**
```
Expected boolean value, got string
```

**Fix:**
```yaml
# Bad
if: ${{ 'true' }}  # String, not boolean

# Good
if: ${{ true }}
if: ${{ success() }}
if: ${{ github.event_name == 'push' }}
```

### 3. Script Injection Vulnerabilities

**Warning:**
```
Potential script injection via untrusted input
```

**Fix:**
```yaml
# Bad - vulnerable to injection
run: echo ${{ github.event.issue.title }}

# Good - use environment variables
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"
```

## Action Errors

### 1. Action Not Found

**Error:**
```
Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/work/_actions/actions/chekout/v4'
```

**Common Causes:**
- Typo in action name
- Invalid action reference
- Action doesn't exist or was removed

**Fix:**
```yaml
# Bad
- uses: actions/chekout@v4  # Typo

# Good
- uses: actions/checkout@v4
```

### 2. Missing Required Inputs

**Error:**
```
Input required and not supplied: path
```

**Fix:**
```yaml
# Bad
- uses: some-action@v1

# Good
- uses: some-action@v1
  with:
    path: ./my-path
```

### 3. Unknown Action Inputs

**Error:**
```
Unexpected input 'invalid_input'
```

**Fix:**
```yaml
# Check the action's documentation for valid inputs
- uses: actions/checkout@v4
  with:
    # Only use documented inputs
    ref: main
    # Remove undocumented inputs
```

### 4. Deprecated Action Versions

**Warning:**
```
Node.js 12/16 actions are deprecated
```

**Fix:**
```yaml
# Deprecated - Node.js 12 (EOL April 2022)
- uses: actions/checkout@v2

# Deprecated - Node.js 16 (EOL September 2023)
- uses: actions/checkout@v3

# Older - Node.js 20 (EOL April 2026)
- uses: actions/checkout@v4
- uses: actions/checkout@v5

# Current - Node.js 20+/24 (v6)
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
- uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903  # v6.0.0

# Note: Node.js 20 EOL is April 2026, Node.js 22 and 24 are current
```

## Job Configuration Errors

### 1. Invalid Runner Label

**Error:**
```
Unable to locate executable file: ubuntu-lastest
```

**Fix:**
```yaml
# Bad
runs-on: ubuntu-lastest  # Typo

# Good
runs-on: ubuntu-latest
```

Valid runner labels:
- `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-20.04`
- `windows-latest`, `windows-2025`, `windows-2022`, `windows-2019`
- `macos-latest` (now macOS 15), `macos-15`, `macos-14`, `macos-26` (preview)
- `macos-13` (RETIRED November 14, 2025 - no longer available)
- `macos-15-intel`, `macos-15-large` (Intel x86_64, long-term deprecated)
- `macos-15-xlarge`, `macos-14-xlarge` (M2 Pro with GPU)
- `gpu-t4-4-core` (GPU runners for ML/AI)
- ARM64 runners (free for public repos)

### 2. Undefined Job Dependency

**Error:**
```
Job 'deploy' depends on job 'biuld' which does not exist
```

**Fix:**
```yaml
# Bad
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # Typo

# Good
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build
```

### 3. Circular Job Dependencies

**Error:**
```
Circular dependency detected
```

**Fix:**
```yaml
# Bad
jobs:
  job1:
    needs: job2
  job2:
    needs: job1  # Circular!

# Good
jobs:
  job1:
    runs-on: ubuntu-latest
  job2:
    needs: job1
```

## Schedule Errors

### 1. Invalid CRON Syntax

**Error:**
```
Invalid CRON expression: '0 0 * * 8'
```

**Fix:**
```yaml
# Bad
schedule:
  - cron: '0 0 * * 8'  # Day 8 doesn't exist

# Good
schedule:
  - cron: '0 0 * * 0'  # Sunday

# CRON format: minute hour day month weekday
# Minute: 0-59
# Hour: 0-23
# Day: 1-31
# Month: 1-12
# Weekday: 0-6 (0 = Sunday)
```

### 2. Multiple Schedule Entries

```yaml
# Correct way to define multiple schedules
on:
  schedule:
    - cron: '0 0 * * 1'  # Monday at midnight
    - cron: '0 12 * * 5'  # Friday at noon
```

## Path Filter Errors

### 1. Glob Pattern Best Practices

**Note:** `**.js` (double-star without a slash) is **not flagged by actionlint** as an error. GitHub's glob engine treats it similarly to `**/*.js`, but `**/*.js` is the conventional and explicit form. Prefer it for clarity.

```yaml
# Not recommended (ambiguous intent, but accepted by actionlint and GitHub)
on:
  push:
    paths:
      - '**.js'

# Recommended (explicit and conventional)
on:
  push:
    paths:
      - '**/*.js'
      - 'src/**'
```

## Environment and Secrets

### 1. Secret Not Found

**Error:**
```
Secret MY_SECRET not found
```

**Fix:**
- Ensure the secret is defined in repository settings
- Check secret name spelling (case-sensitive)
- Verify secret scope (repository vs organization vs environment)

```yaml
# Use secrets correctly
env:
  API_KEY: ${{ secrets.MY_SECRET }}  # Must match name in settings
```

### 2. Environment Variables in run

**Common Issue:**
```yaml
# Bad - environment variable not accessible
steps:
  - run: echo $MY_VAR  # May not work on Windows

# Good - use env
steps:
  - name: Print variable
    env:
      MY_VAR: ${{ secrets.MY_SECRET }}
    run: echo "$MY_VAR"  # Unix
    # or
    run: echo $env:MY_VAR  # Windows PowerShell
```

## Matrix Strategy Errors

### 1. Invalid Matrix Configuration

**Error:**
```
Matrix configuration is invalid
```

**Fix:**
```yaml
# Bad
strategy:
  matrix:
    os: ubuntu-latest  # Should be an array

# Good
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22, 24]  # Node 16 EOL Sep 2023, Node 20 EOL Apr 2026
```

### 2. Matrix Variable Reference

```yaml
# Correct way to reference matrix variables
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
jobs:
  test:
    runs-on: ${{ matrix.os }}
```

## Conditional Execution Errors

### 1. Always/Cancelled/Failure Conditions

```yaml
# Understanding conditions
steps:
  - name: Run on success (default)
    run: echo "Runs only if previous steps succeeded"

  - name: Run always
    if: always()
    run: echo "Runs whether previous steps succeeded or failed"

  - name: Run on failure
    if: failure()
    run: echo "Runs only if a previous step failed"

  - name: Run on success
    if: success()
    run: echo "Runs only if all previous steps succeeded"
```

## Debugging Tips

### 1. Enable Debug Logging

Set secrets in repository settings:
- `ACTIONS_STEP_DEBUG` = `true` (detailed step logs)
- `ACTIONS_RUNNER_DEBUG` = `true` (runner diagnostic logs)

### 2. Use tmate for Interactive Debugging

```yaml
steps:
  - name: Setup tmate session
    if: failure()
    uses: mxschmitt/action-tmate@v3
```

### 3. Print Context Information

```yaml
steps:
  - name: Dump GitHub context
    run: echo '${{ toJSON(github) }}'

  - name: Dump job context
    run: echo '${{ toJSON(job) }}'

  - name: Dump runner context
    run: echo '${{ toJSON(runner) }}'
```

## Best Practices

1. **Always use specific action versions**: `actions/checkout@v6` not `actions/checkout@main`
2. **Quote strings with special characters**: `name: "My: Workflow"`
3. **Use shellcheck**: Enable shell script linting
4. **Validate locally**: Use act and actionlint before pushing
5. **Use env for secrets**: Never put secrets directly in run commands
6. **Keep workflows DRY**: Use reusable workflows and composite actions
7. **Set timeouts**: Prevent runaway jobs with `timeout-minutes`
8. **Use concurrency**: Cancel redundant runs with concurrency groups

```yaml
# Example of good practices
name: Production Deployment

on:
  push:
    branches: [main]

concurrency:
  group: production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          ./deploy.sh
```

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/common-errors-1) · https://claudary.paisolsolutions.com