When something goes wrong
Find what you see, then do what's next to it.
Starting, stopping and versions
| What you see | Why | What to do |
|---|---|---|
| "The insensical server cannot be reached" | No daemon is running and none could start: 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", at launch | A new version was installed under a running daemon | Press Enter to restart it. Everything keeps running, unless the daemon is too old to make way. Escape leaves it |
| "The server is already the new version, and this window is from before it", at launch | An older application was still running when the server moved on | Press Enter to open the new application, or close the window and open insensical again. Nothing ends |
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 |
| "This window was disconnected", or "Disconnected" in a terminal or browser | You ended that connection from another client, with isc disconnect or Disconnect | Press Enter in the window, any key in a terminal, or reload the page |
"The server did not move to the new version", or isc: the daemon was not moved | The installed isc is missing from where the daemon started, or can't take over | Press Enter to go back. Reinstall, or run isc kill-server and start again (ends what's running) |
daemon: running, but it does not say what it is, from isc version | The daemon is too old to answer, or 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 |
isc: ssh needs your key or password for build | ssh to that machine needs something typed, and a link can't type it | isc host answer build shows what it asks. Give the machine a key (ssh-copy-id build), or load yours with ssh-add |
isc: ssh hasn't met build before | ssh would have asked about the host's key | Run isc host answer build and answer it |
isc: build's host key is not the one ssh has for it | The machine's key changed | Find out why first. ssh-keygen -R build forgets the old key |
isc: build is off | A machine of your tailnet that Tailscale says isn't online | Turn it on, or start Tailscale there |
isc: build has no `isc` where a shell finds it | insensical isn't installed there, or is somewhere ssh doesn't look | Install it there. ~/.local/bin, /usr/local/bin and Homebrew's bin are checked |
isc: build has isc X … and this machine has isc Y … which cannot speak to each other | The two machines have different versions | Install the same version on both (isc host put build puts this one there), then run isc host restart build |
isc: this connection was not given the right to …, which … needs. Its rights are: … | The command ran with --rights and left out a right it needs | Run it with that right, or without --rights |
isc: `isc integrate` asks before it changes an agent's settings, and on another machine there is nobody to ask | isc --host NAME integrate without --status or --yes | Run it in a terminal there, or look with --status and then add --yes |
isc: theme is a setting of the interface, read from the file on the machine the interface runs on | isc --host NAME config was given a setting that isn't the daemon's | Leave --host out |
isc: this daemon was not started as `isc daemon`, so it has no `isc` to do that with | Another program runs the daemon inside itself | Run isc integrate or isc config on that machine |
isc: the link to the other machine was lost, or "is out of reach" in the interface | The machine stopped answering, or ssh ended | Run the command again; the interface retries by itself |
| The update notice appears though nothing was updated | The binaries were rebuilt or reinstalled | Restart when convenient |
Settings and appearance
| What you see | 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 | Same |
| 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 used |
theme = "ghostty" is 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 | Install it from a package, or rebuild the icon cache (see The icon); restart the launcher or panel |
Panes and shells
| What you see | Why | What to do |
|---|---|---|
| A different shell, prompt or completion than in another terminal | Panes run $SHELL; the other terminal runs something else | Set shell = "…" |
| Commands found in other terminals aren't found in panes | The daemon started from a launcher with a short PATH | Set PATH in the shell's start-up files, or run isc kill-server and start it from a terminal |
| On another machine, the first letters of a line show late and the rest at once | Typing is drawn ahead only once the program has shown two letters you typed | Nothing: it keeps passwords from being drawn. type-ahead = "off" makes every letter wait alike |
| On another machine, a letter you typed shows and then goes | The program answered the key with something else, or nothing | Nothing: what's left is what the program has |
| A new variable in a shell profile is missing in panes | The daemon keeps the environment it started with | Same |
Programs over ssh complain about an unknown terminal | The other machine has no xterm-ghostty description | infocmp -x xterm-ghostty | ssh host tic -x -, or term = "xterm-256color" |
| A pane shows the generic terminal icon | It has printed 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, or it holds the sequence that ends one. The card says which | Read the card, then press Enter to paste or Escape to drop |
Ctrl+click on a path shows it in the file manager | It's a directory, a runnable file, or a kind opening could run | Open it yourself, or set open-files-with to your editor |
| A path isn't underlined under the pointer | Paths are looked up only while Ctrl is held | Hold Ctrl |
| An input method does nothing | It's off by default | Set input-method = true |
On a Mac, Alt+B and Alt+F do nothing in a shell, or type ∫ and ƒ | Option types the layout's character | Set option-as-alt = true |
| Search misses text that is on screen | The text wraps across three rows or more; two rows are found | Search for a part on one or two rows |
| A pane doesn't fit its window, and its header says "Sized elsewhere" | Another window, or isc attach, was used last | Click this window, or press the mark |
Ctrl+` doesn't reach a program | That key brings up the scratch pane | Set the key to none in [keys] |
States, agents and notifications
| What you see | Why | What to do |
|---|---|---|
A pane never shows done | The command ran under 30 seconds and reported nothing | Lower long-command, 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 is stuck in a state | A hook or the program reported it and nothing has reported since | isc status explain says who. Run isc status clear, or choose "Forget what this pane's program said it was doing" in the palette |
isc status changes nothing in a pane | The pane's program reports its own state in its terminal, which wins | isc status explain says so. It counts again when the program says it's done or idle, or ends |
A pane stays running or waiting after its program was killed | The program reported in its terminal and never took it back, somewhere insensical can't see it end: through ssh, in a pane started with a command, or under a nested shell. See "Programs that report by themselves" | Same as above |
| A program's reports aren't heard | It runs inside tmux or screen, which don't pass them on | Run it in the pane itself |
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 |
| Nothing reaches your phone | A window, terminal or browser that can type is attached, so you count as there; or the command or address failed; or a notify- setting is mistyped | isc notify --sinks says how the last one went. Set notify-command-when or notify-url-when to always |
isc notify --test says https can't be done on this processor | It lacks what the built-in https needs | Use notify-command with curl |
| A clicked notification selects the pane but the window stays behind | Wayland; see Notifications | Bring the window forward yourself |
| Notifications have no application name or icon | The desktop entry isn't installed | Install it |
| The tray's icon is blank | insensical's icons aren't installed | Install them |
| There's no icon in the tray | The desktop has no tray for status notifier items, or tray is off | On GNOME, add the AppIndicator extension |
| The leader does nothing | The desktop took Ctrl+Space | Pick another leader |