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, and it is not what older copies of the bundled skill reference say.

The exit code is 0 on success and non-zero on failure. Branch on ok, or on zero versus non-zero — never on the specific number. 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 specific numbers in the table above are deliberate and are staying, because customer scripts already branch on them. That is exactly why your script must not join them: notify-cms reports an HTTP error as 9 and a connection failure as 8, never as 1; the CI-shaped commands refuse with 2; and leed site upload has the exit-1-with-ok: true path. A script that tested if [ $? -eq 1 ] would misread the three most common failures as successes.

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 fourteen codes 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 token in your repository’s origin URL is the stale one — the three-credential model and the fix are on CLI authentication.

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>/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 -v for the CLI’s own channels, or DEBUG=Eleventy* leed site build for Eleventy’s internals. Both flags, 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: leed site build --debug 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. 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 one JSON document on stdout. Three paths break it today, and all three are reachable on ordinary work, so they are written here as “if you see this, here is what happened” rather than left for you to debug.

Empty stdout, exit 0. You interrupted leed site build --wrangler --json with Ctrl+C. The signal is forwarded to the wrangler process group, the templates are cleaned up, and the process exits 0 having written nothing. There is no failure to report and no document to parse — treat an empty stdout from that command as “canceled”, not as success.

Empty stdout, exit 1. A Tailwind compilation failure during a --json build exits the process directly, before any document is written. The compiler’s own error goes to stderr; read it there.

Two documents on stdout, so JSON.parse fails. A command emitted its document and then something after the action threw — most reachably, writing the validation-tracking file failed on a read-only or full disk during leed site build --json. The failure is appended as a second envelope. If a parse fails, look at the raw bytes before assuming the first document was wrong: the build may well have succeeded.

None of the three is part of the contract; all three are tracked as defects and are carried on known limitations. 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 -V, the exact command you ran, and the run repeated with -v 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.