DEV Community

Yash
Yash

Posted on

How to Debug GitHub Actions Failures Without Losing Your Mind

#github #cicd #javascript #devops

How to Debug GitHub Actions Failures Without Losing Your Mind

GitHub Actions is great until it fails silently, shows a cryptic error, or works on your machine but not in CI.

Here's the systematic way to debug it.

Step 1: Read the Actual Error

Not the job name. Not "Process exited with code 1." The actual error.

# Add this to any failing step to get full output
- name: Your step
  run: your-command
  env:
    NODE_ENV: test
  continue-on-error: false  # Make sure this is NOT true
Enter fullscreen mode Exit fullscreen mode

Click on the failing step in GitHub's UI and expand it. The real error is usually 3-4 lines below where the job says it failed.

Step 2: Reproduce Locally with Act

Act runs GitHub Actions locally:

# Install act
brew install act  # Mac
# or
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Run your workflow locally
act push

# Run a specific job
act push --job build

# With secrets
act push --secret-file .secrets
Enter fullscreen mode Exit fullscreen mode

Create a .secrets file (add to .gitignore):

GITHUB_TOKEN=your_token_here
DATABASE_URL=your_test_db_url
Enter fullscreen mode Exit fullscreen mode

Step 3: Add Debug Logging 

# Enable GitHub Actions debug logging
# Set in Settings > Secrets and variables > Actions:
ACTIONS_STEP_DEBUG: true
ACTIONS_RUNNER_DEBUG: true

# Or enable in-workflow
- name: Debug - print environment
  run: |
    echo "Node version: $(node --version)"
    echo "npm version: $(npm --version)"
    echo "Working dir: $(pwd)"
    ls -la
Enter fullscreen mode Exit fullscreen mode

Step 4: Cache Problems

One of the most common causes of "works locally, fails in CI":

# Clear your cache if you suspect stale deps
- name: Clear cache
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-
Enter fullscreen mode Exit fullscreen mode

To force a cache bust: change the key value (add a version prefix):

key: v2-${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
Enter fullscreen mode Exit fullscreen mode

Step 5: Check Runner Environment Differences

The GitHub Actions Ubuntu runner is minimal. Things that exist on your machine may not exist in CI:

- name: Check available tools
  run: |
    which python3 || echo "python3 not found"
    which docker || echo "docker not found"
    node --version
    npm --version
    cat /etc/os-release
Enter fullscreen mode Exit fullscreen mode

Common missing things:

  • python2 (removed in recent runners)
  • libssl-dev headers
  • System-level dependencies your npm scripts assume

Install what you need:

- name: Install system dependencies
  run: sudo apt-get install -y libpng-dev libssl-dev
Enter fullscreen mode Exit fullscreen mode

The Most Common GitHub Actions Failures

Error Cause Fix
EINTEGRITY npm error Corrupted lock file Delete and regenerate package-lock.json
Permission denied File permissions chmod +x script.sh before running
Cannot find module Wrong working directory Add working-directory: ./subdirectory
Timeout Step takes too long Increase timeout-minutes: 30
Context access error Secret not set Add secret in repo settings

Quick Debug Workflow 

name: Debug CI
on: push

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"

      - name: Print environment
        run: env | sort

      - name: Your actual steps below
        run: npm install && npm test
Enter fullscreen mode Exit fullscreen mode

I built ARIA to solve exactly this.
Try it free at step2dev.com — no credit card needed.

Top comments (0)