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#

No model provider is set up yet.

Add one with ncode settings providers; see the Quickstart.

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.

Update ncode by re-running the installer. 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.

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.1.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.1.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.
  • Mouse selection does not work: hold Shift while dragging (Option in Terminal.app and iTerm2), or type /mouse off.

The screen looks wrong#

  • Boxes or symbols are misaligned: set Ambiguous-width characters to the other value in Settings → Appearance.
  • 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. When you report a problem, include the lines around the time it closed.

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.