# Exit codes

Every niv command ends with one of these, for a person and a script alike. With `--json`, an error's `code` says more. See [Output for scripts](/p/docs/output-for-scripts).

| Exit | Means                                                                            | What to do                                                                                          |
| ---- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 0    | Done                                                                             |                                                                                                     |
| 1    | Failed, or something waits for you                                               | Read the message; for sync, see `niv holds`                                                         |
| 2    | Usage: a wrong option, a missing value, or a question with no terminal to ask in | Fix the command; add `--yes` or `--space` where it says                                             |
| 3    | Sign-in or keys                                                                  | `niv sign-in`, or give the key file's passphrase (see [Sign in and keys](/p/docs/sign-in-and-keys)) |
| 4    | The folder isn't connected to a Space                                            | `niv connect`, or name the right folder with `--folder`                                             |
| 5    | Offline: Niv can't reach its server                                              | Check the connection and run it again                                                               |
| 6    | Refused: niv won't do it as asked                                                | Read the message: it says what to do first                                                          |
| 130  | Stopped with ctrl+c                                                              |                                                                                                     |

A service manager's `SIGTERM` stops `niv sync` with 0.

## Error codes by exit

**2 (usage):** `usage`, `no-terminal`, `confirm-needed`, `not-a-folder`, `not-a-note`, `note-not-found`, `note-ambiguous`, `not-held`, `nothing-to-compare`, `space-needed`, `space-not-found`, `space-ambiguous`, `except-not-found`, `except-outside`, `address-needed`, `address-invalid`, `address-one-note`, `address-kept`, `stores-not-found`, `stores-several`, `server-url-insecure`.

**1 (failed):** `unexpected`, `server-error`, `not-synced-yet`, `already-syncing`, `sync-running`, `start-failed`, `no-spaces`, `sign-in-refused`, `publish-not-synced`, `publish-failed`, `app-owns-folder`, `stores-in-use`, `disk-full`, `read-only-disk`, `write-denied`, `data-folder-shared`, `native-cache`, `not-built`, `checksum`, `signature`, `stale`, and from `niv holds` `failed`, `unavailable` and `held`.

From `niv sync --once`, the code is what stopped it: `timeout`; a hold, such as `divergence-held`, `action-needed`, `files-to-review`, `held-creates`, `refused` or `encryption-held`; `stopped` or `start-failed`; a state that lasted 2 minutes (`error`, `conflict`, `receive-only`, `in-use`, `encrypting`, `setting-up`, `connecting`); sending that stopped moving for 2 minutes (`sending`); in an encrypted Space, receiving that stopped moving for 2 minutes (`receiving`) or the first full read after an update (`catching-up`: run it again); or `observing` when the Niv app holds the folder but stopped syncing it.

**3 (sign-in or keys):** `not-signed-in`, `already-signed-in`, `session-ended`, `signed-out`, `code-expired`, `code-denied`, `encryption-not-set-up`, `encryption-passphrase`, `key-missing`, `key-passphrase`, `key-passphrase-file`, `key-no-terminal`, `key-file-exposed`, `key-file-unreadable`.

**4 (not connected):** `not-connected`.

**5 (offline):** `offline`.

**6 (refused):** `connected-elsewhere`, `folder-other-space`, `folder-too-broad`, `synced-by-app`, `publish-refused-role`, `publish-local-only`, `publish-sealed-image`, `publish-trashed`, `stores-bound`, `stores-unsent`, `stores-app-differs`, `stores-no-app`. `niv upgrade` on a Homebrew install also exits 6, with an `upgrade` object rather than an error; a copy that can't update itself exits 1 the same way (`"state":"unavailable"`). See [Install and update niv](/p/docs/install-and-update-niv).

## An unexpected error

An error niv has no words for ends with one sentence, never a stack:

```
niv holds stopped on an unexpected error. Run it again. If it happens again, run it with NIV_DEBUG=1 and send what it prints to niv.md/contact.
```

`NIV_DEBUG=1` adds where it happened. It never prints your passphrases or keys.

---

Published with [Niv](https://niv.md/) in the Space Docs.
