skip to content

CI and Editor Integration

Running ESLint where it pays: exit codes and --max-warnings in CI, --cache and --concurrency for speed, lint-on-save in the editor. Asked because lint that fails only in CI is a slow loop.

on this pageshow

questions

6

What exit code does the ESLint CLI return when a run finds only warnings, and how do you make CI fail on them?

level: juniorimportance: must knowfreq 38%

answer

  1. three exit codes, not two
  2. warn is reported, not failing
  3. a threshold flag, default -1
  4. zero turns warnings into a gate
  5. 2 means ESLint itself could not finish

basics

~20 s

Exit 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 s

The 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
bash
$ 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 $?
1

go deeper

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

With ESLint 10, what does the --quiet flag change, and how does it interact with --max-warnings?

level: middleimportance: should knowfreq 16%

basics

~20 s

With ESLint 10, --quiet reports only errors and, since ESLint 9.0.0, does not even run rules set to warn. Add --max-warnings and the warn rules run again: their warnings stay hidden but still count toward the threshold.

open as a page

In VS Code, how do you set up the ESLint extension so it applies ESLint's fixes on save in a repository with several packages?

level: middleimportance: should knowfreq 24%

basics

~10 s

Add source.fixAll.eslint set to explicit under editor.codeActionsOnSave; the extension then applies ESLint's fixes on each save. eslint.codeActionsOnSave.mode picks all, the default, or the faster problems, and eslint.workingDirectories says where ESLint runs.

open as a page

How does ESLint's --cache decide a file can be skipped, and why can cached results be wrong on CI checkouts or with typed rules?

level: seniorimportance: should knowfreq 14%

basics

~20 s

ESLint's --cache reuses a file's stored result while the file and its config look unchanged, judged by modification time and size by default. A fresh clone resets those, so use --cache-strategy content; cross-file rules, typed ones included, can report stale results.

open as a page

Why does a pre-commit hook running `eslint --max-warnings 0` on the staged file list fail on generated files the ESLint config ignores, and what fixes it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

ESLint skips an ignored file named on the command line but reports a one-line File ignored warning for it, and --max-warnings 0 turns that warning into exit code 1. Add --no-warn-ignored so ignored files stay skipped and silent.

open as a page

An ESLint 10 lint job on a large repository takes nine minutes; what does --concurrency change, and when does it not help?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

--concurrency, added in ESLint 9.34.0 and off by default, lints files on worker threads. A number sets the thread count; auto starts one per 50 files, capped at half the cores. Each worker reloads the config, so small runs gain nothing.

open as a page