# Troubleshooting niv

What niv says, why, and what to do. Most messages name their next step; this page adds the why. For the app, see [Troubleshooting](/p/docs/troubleshooting).

## "isn't connected to a Space"

```
~/notes isn’t connected to a Space. Run niv connect, or run niv from a connected folder.
```

The folder has no `.niv`, or it was disconnected. Check the path niv names: it comes from `--folder`, then `NIV_FOLDER`, then the folder you're in. A path that isn't there says so and names where it came from: "There's no folder at /nope/x (from --folder)." Exit 4.

## "is a file, not a folder"

`--folder` or `NIV_FOLDER` points at a note. Give the folder that holds it. Nothing was changed. Exit 2.

## No terminal to ask in

A question with nobody to answer it: an agent, a script, a service. niv doesn't wait; it stops and says what answers the question instead.

- "There’s no terminal to ask which Space, so name it with --space <name or id>." Add `--space`. Exit 2.
- "… Without a terminal, add --yes." Add `--yes` once you're sure. Exit 2.
- "This is the Space's first published page, so its site needs an address." Add `--address <name>`. Exit 2.
- "niv sign-in asks for your passphrases, and there’s no terminal to ask in." Run `niv sign-in` once in a terminal. Exit 2.
- "Sync needs this device’s key passphrase, and there’s no terminal to ask in. See niv help keys." Give it with `NIV_KEY_PASSPHRASE_FILE`. Exit 3.

## "Niv can't reach its server"

No connection, a proxy or firewall in the way, or Niv is down. Nothing changed; run it again. Exit 5. A running `niv sync` keeps trying by itself and says `can't reach Niv` meanwhile.

## Sync stops with "waiting for you"

```
13 files are waiting for you before they join Simple test. To see them: niv holds . --show --folder ~/'Field notes'
```

Something waits for your choice. Run the command it prints, then `niv holds <path> --<choice>`. See [Holds in the terminal](/p/docs/holds-in-the-terminal). Exit 1.

## A file you deleted or moved comes back as a question

You deleted it, or moved it and changed it, while no sync was running (a move that left the file unchanged is followed by itself). niv can't tell, so it asks: `--deleted`, `--moved-to <path>`, or `--keep-both`. Move files while sync runs to avoid it.

## "The Niv app is syncing this folder, so niv waits"

The app has the folder open. niv takes over by itself when the app quits or closes the folder. Nothing is lost. See [Sync status](/p/docs/sync-status).

## "already syncing"

```
Niv is already syncing this folder (process 28308), so this one stops. If no niv is running, delete ~/notes/.niv/headless.lock and try again.
```

Another `niv sync` or live view runs on this folder; only one runs at a time. Leave it running, since it's already sending your edits, or stop that process. Delete the lock file only when no niv is running. Exit 1.

## "already connected to"

Connecting a folder again to the same Space changes nothing (exit 0). A folder syncs with one Space: to connect it to another, run `niv disconnect` in it first (exit 6 until you do).

## Sign-in and keys

- **"That passphrase doesn't open this device's key file."** It's the key file's passphrase, not your encryption passphrase. Exit 3.
- **"This device's key file isn't at …"** Set `NIV_KEY_FILE` to where it is, or run `niv sign-in` again. Exit 3.
- **"Other users on this computer can read or change this device's key file"** Run the `chmod` it prints. Exit 3.
- **"This computer’s sign-in to Niv has ended."** The device was removed, or its sign-in expired. Run `niv sign-out`, then `niv sign-in`: sign-in won't start while the old key file is there. Exit 3.

## The sync data

`niv stores` lists every folder's sync data on this computer, with what each waits for and the command to deal with it. A folder that's gone, or one you won't sync again, can be forgotten with `niv stores --forget <folder>` (add `--yes` without a terminal): its notes stay in the folder and in the Space. It refuses a connected folder and unsent edits (exit 6). See [Connect a folder](/p/docs/connect-a-folder).

Where it lives: `NIV_DATA_DIR`, or `~/.local/share/niv` (`XDG_DATA_HOME` when set), or `%LOCALAPPDATA%\niv` on Windows. niv won't use a folder other users can open or change: it says which `chmod` to run, or to set `NIV_DATA_DIR`.

## "stopped on an unexpected error"

niv hit something it has no words for. Run it again. If it happens again, run it with `NIV_DEBUG=1` and send what it prints to niv.md/contact. Exit 1.

## Environment variables

|                                                 |                                               |
| ----------------------------------------------- | --------------------------------------------- |
| `NIV_FOLDER`                                    | The folder, when `--folder` isn't given       |
| `NIV_KEY_PASSPHRASE`, `NIV_KEY_PASSPHRASE_FILE` | The key file's passphrase, without a terminal |
| `NIV_KEY_FILE`, `NIV_KEY_FILE_CONTENT`          | Another key file, or its contents             |
| `NIV_DATA_DIR`                                  | Where the sync data lives                     |
| `NIV_DEBUG=1`                                   | Details for an unexpected error               |
| `NIV_THEME`, `NIV_MOTION=off`, `NIV_ASCII=1`    | How the live view looks                       |
| `NO_COLOR`                                      | No colour, in every command                   |

---

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