Troubleshooting

“This graph was changed on disk while you were editing”

When it appears: desktop only. The file watcher noticed the active graph’s JSON file changed outside the app (an external editor, a sync tool, another Nesso window) while you had unsaved edits in memory.

The banner offers two actions:

• Keep my changes: writes your in-memory version to disk, overwriting the external change.
• Reload from disk: discards your in-memory edits and loads the file as it now is on disk. Undo/redo history is cleared in the process.

There’s no automatic merge: pick whichever side of the conflict you want to keep.

Auto-update problems (desktop)

The desktop app checks GitHub Releases once on launch. If checking fails (offline, GitHub unreachable), it stays silent: no banner, no error, just no update for now.

Once an update is found, the banner can show:

• Version X is available: click Install & restart to download and apply it.
• Installing…: download/install in progress; the button is disabled and there is no way to cancel.
• Update failed. Try again?: the download or install step failed (e.g. lost connectivity mid-download). Click Retry.
• Update installed. Restart Nesso to finish: the update was applied to disk, but the app couldn’t relaunch itself automatically. Quit and reopen Nesso manually.

You can dismiss the available/error states for the rest of the session with the banner’s close button; the install-in-progress state has no dismiss, since the install can’t be cancelled once started.

Unsupported project files (desktop)

If you open a project folder whose graph files come from a newer Nesso version or use an unknown vocabulary, Nesso blocks the project and shows a yellow info banner:

This project contains N file(s) not supported by this version of Nesso. Please update the app or remove the files manually.

What happens: the project folder stays intact on disk. Nesso does not create new graphs inside it, does not overwrite any of the unsupported files, and does not switch to that project; the current (previously loaded) project remains active.

How to recover:

• Update Nesso if a newer release supports those files.
• Remove the unsupported files manually from the project folder (Finder / File Explorer), then switch back to the project. Nesso will treat it as an empty project and seed one starter graph.
• Open a different project from the sidebar; the blocked project stays in your list, greyed out, until you resolve it.

Mentor not responding

If a mentor message fails, the reply bubble shows one of two messages, depending on what went wrong:

• Can’t reach the AI endpoint. Check Settings (⌘,) → AI. For local Ollama, run ollama serve. A network-level failure: the endpoint is unreachable, the wrong port, or, on the hosted web app, a CORS rejection from a local Ollama instance. Confirm the base URL in Settings → AI, that Ollama or your server is actually running, and, if you’re on the hosted web app talking to local Ollama, that you started it with OLLAMA_ORIGINS set to the app’s origin (see AI mentor).
• Hmm. My voice failed me. Try again, slowly. The endpoint was reachable but returned an error or a response Nesso couldn’t parse. Check the model name and that the endpoint speaks the OpenAI-compatible chat/completions format.

Desktop mentor requests use the native HTTP client. The desktop capability allows HTTPS and loopback HTTP only. If a desktop endpoint uses non-loopback http://, switch it to https:// or configure a local service on localhost, 127.0.0.1, or ::1. Browser requests continue to follow normal browser CORS rules.

Closing the mentor panel, switching graphs, or clicking New chat aborts any in-flight request without showing an error.

”No AI endpoint configured”

This isn’t a failure: it’s the mentor’s resting state until you’ve set up an endpoint. It appears whenever Mentor is enabled in Settings → AI but the base URL or model field is empty. The input stays disabled until both are filled in. See AI mentor for setup.

Model pull stalls or shows stale results

Model pulling is available only for local Ollama endpoints. When you click Pull in Settings → AI, Nesso streams the download progress from Ollama’s /api/pull endpoint.

If a pull appears stuck:

• Changing settings cancels the pull. Switching the model, base URL, or API key, disabling the mentor toggle, or closing the Settings dialog all abort the in-flight pull so stale progress cannot interfere with a new model selection.
• Ollama must be reachable on the native port. Nesso strips the /v1 suffix from your base URL to reach Ollama’s native /api/pull endpoint. If you configured a non-standard port, make sure Ollama’s native API is running on that same port.
• Progress is purely cosmetic. The pull runs to completion regardless of whether the progress bar is visible. If the pull completes while you are on a different settings tab, the status badge updates when you return to the AI tab.

If the status shows Unauthorized, check your API key. The endpoint rejected the request with HTTP 401 or 403. For hosted providers, make sure the key is valid and has not expired. Local Ollama instances do not require an API key; leave the field empty.