Troubleshooting
When something isn't working, Niv says what happened and what to do next. This page collects the common cases. Your notes are files on your device, so in every case below they're still there.
Signing in
"Couldn't reach Niv. Check your connection and try again." Niv couldn't reach its server. Check your internet connection and try again, or choose Continue offline for now and sign in later.
"Niv pauses sign-in after a few tries." Wait the time it shows, then try again.
The code didn't arrive, or it stopped working. Codes expire after 5 minutes. Choose Use a different email to go back, check the address, and send a new code.
The browser sign-in didn't come back to Niv. Choose Open the browser again. If the browser can't open, Niv offers Use an email code instead. If the sign-in took too long or the link is no longer valid, start again.
"Couldn't confirm your session." You're still signed in; Niv just couldn't reach the server to check. Sync picks up on its own when the connection is back. Choose Try again, or Sign in again instead.
"Niv updated its identity on this Mac, so your saved session didn't carry over." Sign in once in Settings › Account to reconnect your Space.
Signed out
The sync line says signed out. The folder is set up to sync with a Space, but nothing reaches it while you're signed out: no backup, and nobody in the Space sees your changes. Your notes stay on this device and you can keep working. Click the sync line, or go to Settings › Account, and sign in to pick up where sync left off.
Offline
The sync line says offline. Keep writing; your changes sync when the connection is back.
Sync paused
receiving only. Niv can't read one of its own files for this folder, such as .niv/settings.toml, so it stops sending your edits rather than guess which ones are private. You still receive other people's changes. Settings › Sync names the file and the error. Fix the file, and sync resumes.
on hold, files to review, notes need you, changes refused. Sync is waiting for a decision from you. See When sync asks you something.
Sync stopped
The sync line says not syncing. Settings › Sync says why. Common reasons:
Niv can't open its sync records for this folder. Choose Try again. If it keeps happening, reach out before changing anything in the folder.
Niv can't read the folder's sync settings, so it can't tell which Space the folder belongs to. Restore the file from a backup or an earlier version, then restart Niv.
Sync couldn't start for this Space. Restart Niv.
The folder itself is unavailable, for example on a drive that isn't connected. Reconnect it.
Your existing notes are kept in every case.
Niv can't find your folder
If you moved or renamed the folder, or it's on a drive that isn't connected, Niv asks you to select it again. Connect the drive first, or choose Select a folder and pick it in its new place.
A note shows up twice, or a deleted note came back
If the sync line said restored, Niv went back to the last copy of its sync records it could read. Keep what you want and delete the rest.
If your folder is in iCloud Drive or Dropbox, those apps can also create copies like "Name 2". Niv recommends a folder outside them for a Space.
The AI chat
The agent isn't in the list, or says "Not found". Install it in Terminal, then go to Settings › AI and choose Check again. See Set up your agent.
"Sign-in needed".
Sign in with the agent once in Terminal, for example claude or codex login.
"This model needs Codex …" Update Codex, or point Niv at the right one in Settings › AI › CLI tools.
Updates
"Niv couldn't reach releases.niv.md." Check your connection, then choose Try again in Settings › About.
"Niv couldn't verify the update, so it wasn't installed." Nothing changed. Try again later.
Part of the window stopped
If a single part of Niv stops, like a note, the sidebar or a chat, the rest keeps working and the part says so. Choose Try again. If it fails the same way again, restart Niv. Your notes are safe on disk.
Still stuck
Write to hey@niv.md and say what the screen shows.