How to Debug GitHub Actions Failures Without Losing Your Mind
Step 1: Read the Actual Error
Step 2: Reproduce Locally with Act
Step 3: Add Debug Logging
Step 4: Cache Problems
Step 5: Check Runner Environment Differences
The Most Common GitHub Actions Failures
Quick Debug Workflow 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. Not the job name. Not "Process exited with code 1." The actual error. 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. Act runs GitHub Actions locally: Create a .secrets file (add to .gitignore): One of the most common causes of "works locally, fails in CI": To force a cache bust: change the key value (add a version prefix): The GitHub Actions Ubuntu runner is minimal. Things that exist on your machine may not exist in CI: Common missing things: Install what you need: I built ARIA to solve exactly this.
Try it free at step2dev.com — no credit card needed. Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse
# 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
# 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
# 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
# Install act
-weight: 500;">brew -weight: 500;">install act # Mac
# or
-weight: 500;">curl https://raw.githubusercontent.com/nektos/act/master/-weight: 500;">install.sh | -weight: 600;">sudo bash # Run your workflow locally
act push # Run a specific job
act push --job build # With secrets
act push --secret-file .secrets
# Install act
-weight: 500;">brew -weight: 500;">install act # Mac
# or
-weight: 500;">curl https://raw.githubusercontent.com/nektos/act/master/-weight: 500;">install.sh | -weight: 600;">sudo bash # Run your workflow locally
act push # Run a specific job
act push --job build # With secrets
act push --secret-file .secrets
# Install act
-weight: 500;">brew -weight: 500;">install act # Mac
# or
-weight: 500;">curl https://raw.githubusercontent.com/nektos/act/master/-weight: 500;">install.sh | -weight: 600;">sudo bash # Run your workflow locally
act push # Run a specific job
act push --job build # With secrets
act push --secret-file .secrets
GITHUB_TOKEN=your_token_here
DATABASE_URL=your_test_db_url
GITHUB_TOKEN=your_token_here
DATABASE_URL=your_test_db_url
GITHUB_TOKEN=your_token_here
DATABASE_URL=your_test_db_url
# Enable GitHub Actions debug logging
# Set in Settings > Secrets and variables > Actions:
ACTIONS_STEP_DEBUG: true
ACTIONS_RUNNER_DEBUG: true # Or -weight: 500;">enable in-workflow
- name: Debug - print environment run: | echo "Node version: $(node --version)" echo "-weight: 500;">npm version: $(-weight: 500;">npm --version)" echo "Working dir: $(pwd)" ls -la
# Enable GitHub Actions debug logging
# Set in Settings > Secrets and variables > Actions:
ACTIONS_STEP_DEBUG: true
ACTIONS_RUNNER_DEBUG: true # Or -weight: 500;">enable in-workflow
- name: Debug - print environment run: | echo "Node version: $(node --version)" echo "-weight: 500;">npm version: $(-weight: 500;">npm --version)" echo "Working dir: $(pwd)" ls -la
# Enable GitHub Actions debug logging
# Set in Settings > Secrets and variables > Actions:
ACTIONS_STEP_DEBUG: true
ACTIONS_RUNNER_DEBUG: true # Or -weight: 500;">enable in-workflow
- name: Debug - print environment run: | echo "Node version: $(node --version)" echo "-weight: 500;">npm version: $(-weight: 500;">npm --version)" echo "Working dir: $(pwd)" ls -la
# Clear your cache if you suspect stale deps
- name: Clear cache uses: actions/cache@v3 with: path: ~/.-weight: 500;">npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node-
# Clear your cache if you suspect stale deps
- name: Clear cache uses: actions/cache@v3 with: path: ~/.-weight: 500;">npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node-
# Clear your cache if you suspect stale deps
- name: Clear cache uses: actions/cache@v3 with: path: ~/.-weight: 500;">npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node-
key: v2-${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
key: v2-${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
key: v2-${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
- name: Check available tools run: | which python3 || echo "python3 not found" which -weight: 500;">docker || echo "-weight: 500;">docker not found" node --version -weight: 500;">npm --version cat /etc/os-release
- name: Check available tools run: | which python3 || echo "python3 not found" which -weight: 500;">docker || echo "-weight: 500;">docker not found" node --version -weight: 500;">npm --version cat /etc/os-release
- name: Check available tools run: | which python3 || echo "python3 not found" which -weight: 500;">docker || echo "-weight: 500;">docker not found" node --version -weight: 500;">npm --version cat /etc/os-release
- name: Install system dependencies run: -weight: 600;">sudo -weight: 500;">apt-get -weight: 500;">install -y libpng-dev libssl-dev
- name: Install system dependencies run: -weight: 600;">sudo -weight: 500;">apt-get -weight: 500;">install -y libpng-dev libssl-dev
- name: Install system dependencies run: -weight: 600;">sudo -weight: 500;">apt-get -weight: 500;">install -y libpng-dev libssl-dev
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: -weight: 500;">npm -weight: 500;">install && -weight: 500;">npm test
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: -weight: 500;">npm -weight: 500;">install && -weight: 500;">npm test
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: -weight: 500;">npm -weight: 500;">install && -weight: 500;">npm test - python2 (removed in recent runners)
- libssl-dev headers
- System-level dependencies your -weight: 500;">npm scripts assume
