CLI Troubleshooting and Exit Codes

Use this page by searching for the literal string the CLI gave you. Every message below is reproduced exactly as it is printed — including two with typos in them, which are quoted verbatim because that is what you will paste into a search box. The Cause column is where the plain-English explanation lives.

Most failures set the process exit code rather than exiting immediately, so the work that runs after a command — including the once-a-day update check — still happens. And one rule governs everything else here: JSON mode does not change the exit code. The document’s ok field and the process exit code are two separate signals, and they do not always agree.

Exit codes

Branching on failure, not on the exit code

This is the rule to take away from the page.

The exit code is 0 on success and names the kind of failure otherwise: 2 fix the call, 3 satisfy a precondition, 4 retry, 5 ask a person, 1 report a bug. A command may exit non-zero while reporting ok: true when a non-fatal step failed after the result was already determined; the detail is in warnings.

The exit class is derived from error.code by one table, so every failure document also carries it as error.exit, and error.retryable says whether repeating the call unchanged can succeed. The older per-command numbers — 8 and 9 from notify-cms, 2 for every CI-shaped refusal — are retired. A script that tested if [ $? -eq 1 ] would have missed most failures then and misreads them now; test the class, or parse the document.

In JSON mode, the reliable shape is:

doc=$(leed site push --json) || true
if [ "$(printf '%s' "$doc" | jq -r .ok)" = "true" ]; then
  printf '%s' "$doc" | jq -r '.warnings[]?'
else
  printf '%s' "$doc" | jq -r '.error.code, .error.message, .error.hint'
fi

Parse stdout, read ok, branch on error.code. The code enum is closed, so a switch over it can be exhaustive — the fifteen codes, their exit classes and what each one means are on the machine-readable output page, along with the envelope those fields live in.

“You cannot ‘commit’ directly”

This is the error most people meet in their first week, and it is not a bug.

	You cannot 'commit' directly, please use:

		leed site commit -m "update details"

The process exits 18, and nothing is committed.

leed site init installs three husky hooks into your repository: pre-commit, pre-push and commit-msg. The first two run git config --get leed.invoked and refuse unless it reads true — a flag only the CLI sets, and only for the duration of its own git call. A git push you run yourself gets the same treatment with leed site push in the message.

The third hook checks the message itself. A commit message that does not begin @leed/site-management=> and carry a JSON payload with userId, version and message is rejected the same way:

	You cannot commit directly to this repo, please use:

		leed site commit -m "reason for update"

The rule exists because a commit that skipped the CLI skips three things the platform depends on: file validation, the build gate, and the metadata the CMS reads to attribute the change and trace a failed build back to a CLI release. The reasoning in full is on validate, commit and push.

Only committing and pushing are intercepted. git status, git log, git diff, git branch, git checkout and git pull --rebase all behave normally, and you are meant to use them.

Setup and authentication problems

The first two rows are the only messages on this page that the CLI prints with backticks of its own, around the command it is suggesting. They are set in ordinary type here rather than as code so that those backticks survive to the screen — copy the row and the two strings match your terminal character for character:

Site configuration not initialized. Run `leed site init`!!!
Site configuration already complete! Try running a build `leed site build`

“Signed in” and “able to git fetch” are different states, because they rest on different credentials. If leed auth status shows a valid session but git refuses you, the stored raw-content token is the stale one, and leed auth rotate replaces it — the three-credential model is on CLI authentication.

“Your session is no longer valid. Please re-authenticate to continue.” — or, under --json, auth_expired with “The stored session for … is no longer valid.” — means the CMS refused the stored session. A CLI session lasts 90 days from its last use, so that now has three causes: the session went unused for longer than that plus the 24-hour grace; it was ended by leed auth logout, leed auth reset or a revoke from another device; or it is a login from before CLI sessions became 90-day sessions, which the CMS will not renew. Each takes one leed auth login. Running commands in parallel is no longer a cause — they share one renewal under a lock on auth.json, and a token another command has just replaced keeps working for 60 seconds — and a rate-limited session check (HTTP 429) is reported as network_error, exit 4, not as an expired session. Wait a minute and retry it.

Validation, commit and push problems

A rebase conflict aborts the rebase and leaves your work intact. The recovery is ordinary git:

cd ~/leed/<your-domain-slug>/raw-content
git pull --rebase
# resolve the conflicts, then:
git rebase --continue
leed site push

That git pull --rebase is explicitly permitted by the hooks. Why the repository rebases rather than merges, and who else writes to it, is on Git workflow. Which files validation protects, and why some are restored on sight, is on editable and read-only files.

Build problems

Build failure output is summarized rather than dumped, which is worth knowing before you conclude that something was swallowed. The CLI scans the subprocess output for lines carrying ✘, [ERROR], a leading Error:, Failed: or fatal:, and keeps each such line together with the indented lines that follow it. When it finds no marker at all it falls back to the raw output. Either way the result is trimmed to its last 2,000 characters, so a very long failure is shown from its end, not its beginning. If that is not enough, re-run with --verbose for the CLI’s own channels, or DEBUG=Eleventy* leed site build for Eleventy’s internals. Both, and the recording rule that decides whether a build counts, are on leed site build.

OpenAPI import problems

The --debug trap deserves repeating because it looks like the CLI is ignoring you: a build you run with -d is deliberately not recorded as a successful build, so a developer with -d in their muscle memory can build ten times and still be told to build. (--serve skips minification by itself and still counts.) The whole workflow, with the two guards drawn as a diagram, is on importing an OpenAPI spec; the flags are on OpenAPI commands.

Eject problems

Each template, what it controls and what you take responsibility for by ejecting it are on leed site eject.

Installer problems

The one-line installer runs under set -euo pipefail, so any of these ends the run with exit 1.

Re-running the installer is safe and idempotent — it reuses valid credentials, skips prerequisites that are already satisfied, and asks before overwriting an existing leed.config.json. The full walkthrough is on installing the Leed CLI.

When there is no document at all

Under --json the contract is exactly one JSON document on stdout, and the three paths that used to break it are closed. An interrupted leed site build --wrangler --json now writes its document, with the interruption in warnings, and exits 130 on Ctrl+C or 143 on SIGTERM. A Tailwind failure during a --json build is reported as a failure document instead of exiting with an empty stdout. And a failure after the action has already emitted no longer appends a second envelope.

An empty stdout therefore means the process was killed outright — by the out-of-memory killer, a forced kill, or a CI runner timing out — before it could write anything. Treat it as a failure, and read stderr for what the process managed to say.

What the document is supposed to look like is on machine-readable output (--json).

When nothing else works

Three repairs, in increasing order of how much they touch. Try them in order.

If none of that helps, a useful report has three things in it: the output of leed --version, the exact command you ran, and the run repeated with --verbose so the leed:* diagnostic channels are on. Add --json if the failure is in a script — error.code and error.details say more than the rendered text does.

When the failure is a wrong flag rather than a wrong state, the command’s signature is at CLI command reference, and every path and variable named on this page is cataloged on leed.config.json, files and environment. Errors from the rest of the product — the CMS, the editor, the site build — are collected in common error messages, which links back here rather than duplicating this catalog.