ncode

CLI docs Troubleshooting

ncode CLI Help

Troubleshooting

ncode says what went wrong in one sentence and what to do in a second one. This page collects those sentences, and a few problems that come from the terminal or macOS.

It refuses to start (exit code 3)#

The app is open#

The ncode app is open, and only one of them can use your conversations at a time.
Quit the ncode app, then run ncode again.

The desktop app is running under your user account. Quit it with ⌘Q (closing its window is not enough) and run the command again. Only ncode --version and ncode --help work while the app runs. See Works with the desktop app.

Another session is open#

Another ncode (process 48213, since 09:41) is already using your conversations.
Close it first (Ctrl-C twice, and once more if it asks), then run ncode again.

Another ncode session, in another terminal window or tab, holds the database. Close it, or continue your work there. This also applies to ncode -p and to ncode config set on a setting stored in the database.

No provider#

In the full screen, a first run with no provider does not stop: ncode opens Settings at Providers with the note Add a model provider to start: pick a preset, paste its key. For -p, --plain and any run without a terminal, it stops with exit code 3:

No model provider is set up yet.

Add one with ncode settings providers; see the Quickstart. If you set NCODE_API_KEY, ANTHROPIC_API_KEY or OPENAI_API_KEY for the first run, two more sentences can appear:

NCODE_MODEL is missing.
Set NCODE_MODEL to a model of your provider, or run 'ncode settings providers'.
NCODE_BASE_URL is missing (OpenAI-compatible URLs end in /v1).
Set NCODE_BASE_URL, or run 'ncode settings providers'.

The database needs the app, or a newer ncode#

This ncode database needs an upgrade that only the ncode app makes.

Open the desktop app once, quit it, and run ncode again.

This ncode database was upgraded by a newer ncode app than this ncode supports.
Install the ncode CLI that matches your ncode app (ncode --version shows this one: 0.3.0); the database was not changed.

Update ncode by re-running the installer. The 0.1.0 command refuses a database that a 0.2 app has upgraded, with the first of these two sentences; installing 0.2.0 fixes it, and the 0.2.0 message also names the version. The app and the CLI are numbered separately; keep both on the 0.2 line (ncode 0.3.0 goes with ncode 0.3.0). In both cases nothing in the database was changed.

The data folder#

ncode could not safely open its private data folder.

~/Library/Application Support/SwarmCode must belong to you and have mode 0700. Check it with ls -ld and fix it with chmod 700 on that folder.

It cannot tell whether the app is running#

ncode could not check whether the ncode app is running.

Re-run the installer, as the message says.

Other database messages#

ncode also stops when it cannot use the database file. The second line of each message says what to do:

  • "The file where your conversations database belongs is not an ncode database." or "Your conversations database failed SQLite's integrity check." The file ~/Library/Application Support/SwarmCode/swarm_code.db was replaced or is damaged, and nothing was changed. Move it aside, or restore it from a verified backup, then run ncode again. The backups ncode makes before it upgrades the database are in the backups folder beside it.
  • "Your conversations database comes from an ncode version this ncode does not know." Update ncode by re-running the installer, or open the desktop app once to upgrade the database.
  • "ncode could not make a verified backup before upgrading the database, so it changed nothing." Free some disk space and run ncode again.
  • "ncode could not upgrade the database; it was left as it was." The verified backup is in the backups folder beside the database. Open the desktop app, or report the problem with the lines from cli.log (see A session closed on its own).
  • "ncode could not open your conversations database." Close other ncode windows and run it again.

The app was opened while a session was running#

A one-line banner says The ncode app is open on the same database. Quit it, or stop your runs here and quit (Ctrl-C twice). Only one of the two can use your conversations at a time; see Works with the desktop app.

command not found: ncode#

~/.local/bin is not on your PATH. Add it as shown in Install, then open a new terminal window.

macOS blocks it, or a dyld error names a macOS version#

  • "cannot be opened because the developer cannot be verified", or a similar Gatekeeper message: ncode 0.3.0 is a developer preview that is not notarized, so macOS blocks it when the archive carries a quarantine mark, which browsers add and curl does not. Remove the mark as shown in Install the release by hand; the one-line installer is not affected.
  • A dyld error that names a macOS version means the Mac runs an older macOS than ncode was built for. ncode 0.3.0 needs macOS 15 or later on Apple silicon (arm64).

Keys do something unexpected#

  • Option does not work as Alt in some terminals (Ghostty on macOS in particular). Nothing essential needs Alt: queue with Tab instead of Alt+Enter, and use Ctrl+G for the runs dashboard instead of the Alt run-tab keys.
  • A letter answered nothing: approval letters work only while your draft is empty; clear the draft (Ctrl+C) first.
  • The wheel does not scroll, or it walks through earlier prompts: by default ncode relies on the terminal sending arrow keys for the wheel (alternate scroll). A terminal that sends one arrow per notch looks like ↑ and ↓; type /mouse on to get real wheel reports instead.
  • Mouse selection does not work: with /mouse on, hold Shift while dragging (Option in Terminal.app and iTerm2), or type /mouse off to give the terminal its own selection back (the default).
  • No bell or notification when an approval waits: ncode only signals while the terminal says it is not in front, and not every terminal reports that. Check terminal.notify (auto, bell, osc9, os or off) and your terminal's own bell and notification settings.
  • Ctrl+V attaches no image: it needs macOS and a local session; it says The clipboard has no image. when there is none and Over SSH the clipboard is the other Mac's; use /attach PATH. over SSH.

The screen looks wrong#

  • Boxes or symbols are misaligned: set Ambiguous-width characters to the other value in Settings → Appearance.
  • The screen is garbled after something else wrote to the terminal: press Ctrl+L to redraw it.
  • Symbols are missing or show as question marks: start with NCODE_ASCII=1 ncode, or set Glyphs in Settings → Appearance.
  • Colours are wrong: NO_COLOR=1 ncode gives a monochrome screen. The richest glyphs need a truecolor terminal (see Terminal, themes and mouse).

A session closed on its own#

The reason is in cli.log; ncode config path prints where it is. A message points to cli.log only when it has something in it. When you report a problem, include the lines around the time it closed. If a screen update fails, ncode keeps the last good screen and says A screen update failed; showing the last good one.; it closes only after five failures in a row.

Ctrl+C ended the program#

That is expected outside the full screen: while it starts, during a -p run, or after the exit summary, Ctrl+C simply ends ncode.

Check the setup#

sh
ncode config doctor

checks the files and the environment ncode relies on and says what is wrong, with a hint for each problem; ncode doctor is the same. It exits 1 only for a blocking problem.