Skip to content

Process Completed With Exit Code 1: How to Debug

Last updated

Error: Process completed with exit code 1. is not the real error. It is GitHub telling you that a command in a run step returned a non-zero status, and the step failed. The cause is in the log lines above it. This page shows how to find those lines, how to reproduce the failure, and the causes that come up most often.

The exact message

Error: Process completed with exit code 1.

Exit code 1 is the general "something went wrong" status. Many tools use it: test runners when a test fails, linters when they find issues, grep when it finds no match, npm when a script fails. Other codes have more specific meanings, such as 137, 143, 127 and 128.

Step 1: find the real error

Expand the failing step and read upward from the red line. The first message that looks like an error (a stack trace, a failed test, npm ERR!, error:) is the cause. If the log is long, use the search box in the log viewer for error, fail and fatal.

If there is nothing useful, turn on debug logging. Re-run the job and tick "Enable debug logging", or set the repository secret or variable ACTIONS_STEP_DEBUG to true. In shell steps, print each command as it runs:

- name: Build
  run: |
    set -x
    npm ci
    npm run build

Step 2: understand how GitHub runs your script

With shell: bash set explicitly, GitHub runs bash --noprofile --norc -eo pipefail {0}. Without a shell setting on Linux it runs bash -e {0}. In both cases the step stops at the first failing command, and with pipefail a failure anywhere in a pipeline fails the whole step. The step's exit code is the code of the command that failed.

Common causes and fixes

1. A test, lint or build command failed

The most common case. Run the same command locally, with the same Node, Python or Java version as the workflow, and fix what it reports.

2. The lockfile does not match

npm ci fails with exit code 1 when package-lock.json and package.json disagree. Regenerate the lockfile locally with npm install, commit it, and use the same package manager version as CI.

3. grep or diff found nothing, or something

grep exits 1 when there is no match, and diff exits 1 when files differ. Both are normal outcomes that fail the step. If a no-match is acceptable, say so:

- run: grep -q "ready" status.txt || echo "not ready yet"

Do not append || true to a command whose failure matters, because that hides real errors.

4. A missing environment variable or secret

Secrets are empty in workflows triggered from forks and in some Dependabot runs, and scripts that need them then fail. Print whether it is set, without printing the value:

- run: test -n "$API_TOKEN" || { echo "API_TOKEN is empty"; exit 1; }
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}

5. It works locally but not in CI

Different tool versions, a different operating system or case-sensitive file names. Pin versions with setup-node, setup-python or setup-java and check that import paths match the real case of file names.

If a failure is expected

Use continue-on-error: true on a step only when you genuinely do not want it to fail the job, and check its result later through steps.<id>.outcome.

How to prevent it

  1. Run the same commands locally with the same versions, ideally from one script that CI also calls.
  2. Pin runtime and tool versions instead of using floating ones.
  3. Print the failing tool's version and the working directory at the start of each job.
  4. Keep steps small, so the failing step names the problem.
  5. Do not mask failures with || true.

FAQ

What does exit code 1 mean in GitHub Actions?

The command returned status 1, the general failure code. GitHub marks the step as failed. What went wrong is in the output above the message.

Why is there no error above "exit code 1"?

The tool may have printed errors to a file, or a log group may be collapsed. Expand all groups, then enable debug logging and re-run.

Is exit code 1 the same as 0?

No. Exit code 0 means success. Any other code fails the step unless you set continue-on-error.

Can I make a step ignore exit code 1?

Yes, with continue-on-error: true or by handling the command in the script. Only do this when the failure truly does not matter.