What exit code does the ESLint CLI return when a run finds only warnings, and how do you make CI fail on them?
answer
- three exit codes, not two
- warn is reported, not failing
- a threshold flag, default -1
- zero turns warnings into a gate
- 2 means ESLint itself could not finish
basics
~20 sExit code 0: warnings alone never fail an ESLint run, and only errors return 1. Add --max-warnings 0 and any warning makes ESLint exit with 1; exit code 2 means ESLint itself hit a configuration problem or crashed.
solid answer
~40 sThe ESLint CLI has three exit codes. `0` means no errors, and no more warnings than `--max-warnings` allows when that flag is set. `1` means at least one error, or more warnings than `--max-warnings` allows. `2` means linting did not succeed because of a configuration problem or an internal error. A rule set to `"warn"` is reported but never changes the exit code on its own, so a CI step running `eslint .` stays green however many warnings it prints. `--max-warnings` defaults to `-1`, meaning no threshold; `--max-warnings 0` makes a single warning exit with `1` and prints `ESLint found too many warnings (maximum: 0).` The warnings stay warnings in the report; only the exit code changes.
code
bash · 10 lines$ npx eslint .
✖ 37 problems (0 errors, 37 warnings)
$ echo $?
0
$ npx eslint --max-warnings 0 .
✖ 37 problems (0 errors, 37 warnings)
ESLint found too many warnings (maximum: 0).
$ echo $?
1go deeper
Recall the three codes: 0 clean, 1 an error or too many warnings, 2 ESLint could not run. Know that warnings alone return 0 and that --max-warnings 0 changes that.
Explain that severity decides what is reported while the exit code decides what fails, and that --max-warnings bridges them without touching the config. Show where the threshold check counts.
When a lint step goes red, read the exit code first: 2 sends you to the config, formatter or patterns, 1 to the code. Know that a parsing error is exit 1 unless --exit-on-fatal-error is set.
Weigh a zero-warning gate against a numeric ceiling: zero makes every warn rule a blocker, a ceiling stops growth without forcing a cleanup. Either way, keep the flag in the shared script, not only in CI.
## The three exit codes A CI system decides pass or fail from the **exit code** a command returns: `0` is success, anything else is failure. The ESLint CLI documents exactly three codes: | Exit code | Meaning | |---|---| | `0` | Linting succeeded and found no errors. If `--max-warnings n` is set, there are at most `n` warnings. | | `1` | Linting succeeded and found at least one error, or more warnings than `--max-warnings` allows. | | `2` | Linting was unsuccessful because of a configuration problem or an internal error. | The split between `1` and `2` matters when you read a red pipeline. Code `1` means ESLint did its job and found at least one error, or more warnings than the threshold allows. Code `2` means ESLint could not do its job at all, and the fix is in the setup, not in the source files. ## Why warnings never fail a run by default Every rule has a **severity**: `"off"` (`0`), `"warn"` (`1`) or `"error"` (`2`). ESLint's own glossary describes `"warn"` as running the rule without exiting with a non-zero status because of its violations, with `--max-warnings` as the only exception. So a codebase whose config sets most rules to `"warn"` can print hundreds of warnings on every pull request and still return `0`. The report is visible; nothing enforces it. This is the most common surprise for someone new to a lint job: the log is full of yellow, and the check is green. ## Turning warnings into a gate with `--max-warnings` `--max-warnings` takes an integer threshold. Its default is `-1`, which means no threshold. When the flag is set and the total warning count is **greater** than the number you pass, ESLint exits with `1` and prints `ESLint found too many warnings (maximum: n).` after the report. 1. `eslint --max-warnings 0 .` fails on the first warning, which makes every warning-level rule a merge blocker without editing the config. 2. `eslint --max-warnings 25 .` passes with 25 warnings and fails at 26, so the count cannot grow past today's number. 3. Errors are not affected by the flag: one error still returns `1` whatever the warning count. The flag changes only the exit code. The warnings are still printed as warnings, and their rules keep their configured severity. If you want a rule to be an error everywhere, that is a change to its severity in the config, not a CLI flag. ## What exit code 2 points at Code `2` is ESLint saying it never produced a trustworthy result. Typical causes: - the config file throws while loading, or no `eslint.config.*` file can be found; - the formatter named with `-f` cannot be loaded; - a file pattern on the command line matches no files; - an unexpected crash, printed under `Oops! Something went wrong! :(` with the ESLint version. A **parsing error** in one file is different. By default ESLint reports it as an error-level message on that file, so the run returns `1` like any other error. Only `--exit-on-fatal-error` turns a parsing error into exit code `2`. ## How other flags move the exit code A few flags change what the exit code is computed from, and it pays to know which: - `--fix` writes fixes to the files first; the remaining, unfixed problems are what gets reported and what decides between `0` and `1`. - `--quiet` hides warnings from the report but does not change the code: a warnings-only run returns `0` with or without it. - `--exit-on-fatal-error` moves parsing errors from `1` to `2`, so a file ESLint cannot parse is treated like a setup failure rather than a rule violation. - `--max-warnings` is the only flag that lets warnings decide the result. ## Reading the result in CI The report format does not change the exit code. `-f json -o eslint-report.json` writes a JSON report to a file for another tool to read, while the step still passes or fails on the same `0`, `1` or `2`. The default console format is `stylish`, which ends with a summary line such as `✖ 37 problems (0 errors, 37 warnings)`. ```bash npx eslint . echo $? # 0: warnings only npx eslint --max-warnings 0 . echo $? # 1: too many warnings ``` Three habits follow from this: - Treat `2` as an infrastructure failure: read the message ESLint printed before looking at any source file. - Put `--max-warnings` in the same script developers run locally, so the local run and the CI step agree on what fails. - Do not reach for `--quiet` to make a warnings-only run pass. It hides warnings from the output, and a run with only warnings already returns `0`.
- A CI step running ESLint exits with 2 instead of 1. Where do you look first?At the message ESLint printed, not at the source files. Exit code `2` means linting itself failed: a config file that throws or cannot be found, a formatter named with `-f` that cannot be loaded, a file pattern that matches nothing, or a crash shown under `Oops! Something went wrong!`. A rule violation, even a parsing error, gives `1` unless `--exit-on-fatal-error` is set.
- Does `--max-warnings 0` turn the warnings into errors in the report?No. Each problem keeps its configured severity and is printed as a warning; only the exit code changes, and ESLint adds `ESLint found too many warnings (maximum: 0).` after the report. To make a rule an error in the report and in the editor, change its severity in the config instead.
- How do you save a machine-readable report without changing whether the step fails?Choose a format with `-f` and a destination with `-o`, for example `eslint -f json -o eslint-report.json .`. The report goes to the file instead of the console, and the exit code is still computed from the same errors and warnings, so the step passes or fails exactly as before.
- A rule set to warn will fail the build once enough warnings pile up.
- The default value of --max-warnings is 0.
- Exit code 2 means the code has more serious lint problems than exit code 1.
- --max-warnings 0 rewrites every warning as an error in the report.
- Errors are let through as long as the warning count stays under --max-warnings.