Reading and Debugging Workflow Run Logs

When a workflow goes red, the logs tell you exactly what happened - if you know how to read them.

Sooner or later a workflow will fail, and your ability to ship depends on quickly understanding why. This lesson teaches you how to navigate run logs, isolate the failing step, and turn on extra debugging when you need more detail.

Navigating to the logs

Open the Actions tab, click the workflow run you care about, and you will see its jobs. A red X marks a failed job. Click the job to expand its steps; each step can be expanded to reveal its console output. The failing step is highlighted, so you can jump straight to where things went wrong.

Finding the real error

Start at the first failed step - later failures are often just fallout from it.
Read upward from the bottom: the final lines usually contain the actual error and exit code.
A non-zero exit code is what fails a step; search the output for the command that produced it.
Distinguish a real failure from a flaky one (a network blip) before assuming your code is broken.

Enabling step debug logging

For stubborn problems, GitHub Actions can emit verbose debug output. Set the repository (or workflow) secret/variable ACTIONS_STEP_DEBUG to true and re-run the job. You will get detailed internal logging from steps and actions, which often reveals issues that the normal output hides.

Re-running and isolating

Use "Re-run failed jobs" to retry after a fix or to check whether a failure was transient. To probe interactively, you can add a temporary diagnostic step that prints environment details. Remember that some failures are infrastructure-related rather than code-related; managed runner platforms like Latchkey automatically retry transient infrastructure failures so those do not surface as false negatives.

temporary debug step

steps:
  - name: Debug environment
    run: |
      echo "Node: $(node -v)"
      echo "Working dir: ${{ github.workspace }}"
      env | sort

Key takeaways

Start at the first failed step and read the final output lines for the real error.
Set ACTIONS_STEP_DEBUG=true for verbose internal logging on a re-run.
Re-running helps distinguish a code bug from a transient infrastructure blip.