CircleCI "exited with code 1" - Diagnose Step Failures

A command in a run step returned a non-zero exit code, so CircleCI fails the step and the job. Exit 1 is a genuine failure of whatever the step ran - not an infra problem.

What this error means

A step ends with "exited with code 1" right after a tool printed its own error (failing tests, a lint violation, a compile error). The job stops at that step.

job log

#!/bin/bash -eo pipefail
npm test

Tests:       3 failed, 41 passed
npm ERR! Test failed.  See above for more details.

Exited with code exit status 1

Common causes

The command genuinely failed

Tests failed, a linter found violations, or a build errored. The tool exits non-zero and CircleCI faithfully fails the step.

A piped command’s failure surfaced via pipefail

CircleCI runs steps with -eo pipefail, so a failure anywhere in a pipeline (not just the last command) fails the step.

Environment difference vs local

It passes locally but fails in CI due to a missing env var, a different tool version, or a clean checkout exposing an uncommitted file.

How to fix it

Read the tool output above the exit line

Scroll up from "Exited with code 1" - the real error is the tool’s own message just above.
Fix the failing tests, lint rule, or build error it reports.
Reproduce locally with the same command the step ran.

Handle expected non-zero exits explicitly

If a command is allowed to fail, handle it rather than letting pipefail abort the step.

.circleci/config.yml

- run:
    name: Lint (non-blocking)
    command: npm run lint || true

Match CI to local

Confirm the same tool versions (use a pinned image / cimg/* tag).
Ensure required env vars/contexts are attached.
Run against a clean checkout to catch uncommitted local files.

How to prevent it

Pin tool versions so CI and local behave the same.
Keep -eo pipefail and fix the underlying command, not the exit code.
Reproduce failures locally with the exact step command.