When something goes wrong

Starting, stopping and versions

What is seen	Why	What to do
"The insensical server cannot be reached"	No daemon is running and none could be started: isc isn't beside the application or on PATH, or the socket's directory isn't private	Put isc beside insensical; check the directory's permissions
"insensical was updated, and the server still running is from before", at launch	A new version was installed under a running daemon	Press Enter to restart it. Everything keeps running; if the daemon is too old to make way, programs end and the layout comes back. Or press Escape to leave it
isc: protocol N does not match the running daemon's M	The same, from the command line	Run isc restart-server
"The server has stopped" in the window	The daemon was stopped or crashed	Press Enter to start it; the layout comes back
"The server did not move to the new version" in the window, or isc: the daemon was not moved	The installed isc is missing from where the daemon was started, or can't take over what it runs	Nothing was lost. Press Enter to go back to it. Reinstall; or run isc kill-server and start again, which ends what's running
daemon: running, but it does not say what it is, from isc version	The daemon is from before the requests that every version answers, or it's stuck	Run isc restart-server
a daemon is already running	isc daemon was run twice	Nothing; or run isc kill-server first
path must be shorter than SUN_LEN	The socket's path is too long	Set a shorter INSENSICAL_SOCKET
The update notice appears though nothing was updated	The binaries were rebuilt or reinstalled	Restart when convenient

Settings and appearance

What is seen	Why	What to do
A red message in the top bar	A setting couldn't be used; the message names the file and line	Fix the line; it applies within a second
All settings seem ignored	One unreadable line voids the whole file	As above
Icons are boxes or missing	The font isn't a Nerd Font	Set font-family to a Nerd Font
Text smaller or larger than expected	font-size is in points	12 points is 16 pixels on Linux
Text thinner than in another terminal	There's no font weight setting	Nothing; the regular face is always used
theme = "ghostty" is reported as an error	Ghostty isn't installed	Use a built-in theme or a theme file
The window has a generic icon	It was run without installing, or the icon cache is old	Run just install or just install-local; restart the launcher or panel

Panes and shells

What is seen	Why	What to do
A different shell, prompt or completion style than in another terminal	Panes run $SHELL; the other terminal was set to run something else	Set shell = "…"
Commands not found in panes that exist in other terminals	The daemon was started from a launcher with a short PATH	Set PATH in the shell's start-up files, or stop the daemon with isc kill-server and start it from a terminal
A new variable in a shell profile is missing in panes	The daemon keeps the environment it was started with	The same
Programs over ssh complain about an unknown terminal	The other machine has no xterm-ghostty description	Set TERM there, or install the description
A pane shows the generic terminal icon	It has printed nothing and been sent nothing, or its program isn't in the list	Nothing
A pasted block waits at the foot of the pane	It has several lines and the program didn't ask for marked pastes	Press Enter to paste it, or Escape to drop it
Accents typed as two keys, or an input method, do not work	Not supported	Nothing
Search misses text that is on screen	The text wraps across two rows	Search for a part that's on one row
A pane does not fit its window	Another window or isc attach resized it	Use one window; leave the attach
Ctrl+` does not reach a program	That key brings up the scratch pane	Set the key to none in [keys]

States, agents and notifications

What is seen	Why	What to do
A pane never shows done	The command ran for under 30 seconds and reported nothing	Use isc status from a hook, or a program that reports progress
A failed command shows done	The shell doesn't mark its commands	Use fish 4, or the isc shell-integration line for bash or zsh
A pane stuck in a state	A hook reported it and nothing has reported since	isc status explain, isc status idle
A Gemini CLI pane stays running after a failed or cancelled turn	Gemini CLI has no event for either	The next prompt clears it; or run isc status idle
Hooks stopped reporting	isc moved since integrate	Run isc integrate for that agent again
Codex reports nothing	Its hooks aren't trusted	Run /hooks in Codex
The bell marks a pane but no notification arrives	The bell never notifies	Nothing
A clicked notification selects the pane but the window stays behind	Wayland; see Desktop notifications	Bring the window forward yourself
Notifications have no application name or icon	The desktop entry isn't installed	Install
The leader does nothing	The desktop took Ctrl+Space	Pick another leader