When something goes wrong

Last updated: 2026-11-01

When a shell is not simply running, a line under its pane takes the place of the status line and says why, with what you can do about it. For a shell in a keeper, Running says the same in a word or two, and its dot turns red when a shell needs you (see Shells that keep running); a plain shell is not listed there. Start from what they say.

A connection was lost, or a host is not reached#

While SpectaShell is still trying, there is nothing you need to do: it tries again by itself, at once and then less often, up to every 30 seconds, and at once each time the app comes back to the screen or the network changes. Once the host has been out of reach for a minute, Reconnect tries at once.

When the host stays out of reach, check that:

• the host is on, and answers from another machine (ssh from a terminal there);
• this device is on the host's network, or on the VPN or Tailscale network that reaches it;
• on an iPad or iPhone, SpectaShell has been allowed the local network, for a host on your own network: Settings ▸ Privacy & Security ▸ Local Network. On a Mac, the same switch is in System Settings ▸ Privacy & Security ▸ Local Network.

When the connection ended for good:

• A shell in a keeper is still on the host. Reconnect takes it up again where it was, with its screen.
• A plain shell ended with its connection, and the pane says "Nothing on host kept this shell." Reconnect opens a new shell there. To have shells that outlive a lost connection, let the host keep them (see Shells that keep running).

On an iPad or iPhone, a plain shell usually ends whenever SpectaShell leaves the screen for more than a moment (see On the iPad and iPhone).

Could not connect#

"Could not connect to host" is followed by the reason, such as a host that refused the login or an address that did not answer. Show Logs beside it opens the Connection Log: each step the connection took, with the milliseconds since it began, for every attempt the pane made. Show Logs is also on the card a pane shows while a connection takes a while, over the steps it goes through: Reaching the host, Checking its key, Logging in, Starting the shell.

The log says, in words:

• the address it connected to, through which jump host, and how long that took;
• the key the host presented, by its type and fingerprint, and whether it is the trusted one;
• the user name it logged in as, and the keys it offered — the files in ~/.ssh on a Mac, the SSH agent's keys, and this device's key — and which one the host took;
• what the host says and asks: its banner, and each question it asks, such as "Password:" or a verification code;
• the keeper it looked for or put on the host, and the shell it started;
• and why it stopped, on a last line that starts with "Could not connect".

It never holds what you type: a password, a passphrase or a code shows only as asked for, never as answered. Copy puts the whole log on the clipboard, ready to paste into a message.

A line "No route to address yet; the system may still be letting this app onto the local network" means the system has not yet let SpectaShell reach your network; SpectaShell tries again a few times by itself. If it stays, check the Local Network switch above.

A host's key changed#

When a host presents a key other than the one SpectaShell trusts for it, SpectaShell refuses the connection: the pane says "Could not connect to host" and "Its host key changed, so SpectaShell refused the connection." Someone between you and the host could be presenting a different key, or the host was reinstalled.

• If you do not know why it changed, do not connect. Ask whoever runs the host for its key's fingerprint, and compare it with the one SpectaShell shows.
• If you know why — the host was reinstalled, or its address now leads to another machine — choose Forget Old Key… in the pane and again in the dialog that shows both keys, then Forget Key. The old key is forgotten on all your devices, and the next connection asks you to trust the key the host presents now.

Known Hosts lists each host whose new key was refused, with Review…, which shows the same choice. See Hosts and connections.

A password is asked every time#

After you log in to a host with a password alone, SpectaShell asks "Log in to host with this device's key from now on?" Add Key puts this device's key in ~/.ssh/authorized_keys there, and the next login needs no password. Not Now asks again at the next login.

If you are still asked for a password:

• If the key could not go on the host, SpectaShell says so as the shell opens — "This device's key is not on host" — with the host's reason, such as a ~/.ssh there that is not a folder you can write to.
• Show Logs says which keys were offered and whether the host took one. A host can refuse keys in its SSH server's settings, or when your home folder or ~/.ssh there can be written by others.
• Until iCloud has been read, SpectaShell puts no key on any host (see Keys wait for iCloud).
• A host of a team someone else shares is not offered your key: its owner lets members in, host by host (see Teams).
• When this device's passcode was turned on or off, SpectaShell made the device a new key. Log in to each host with its password once and choose Add Key: the new key takes the old one's place.

See Your devices, keys and iCloud.

Keys wait for iCloud#

"Keys wait for iCloud", under this device's name in the sidebar, and Keys on Hosts: Waiting for iCloud in Settings mean SpectaShell has not yet read iCloud since it started. Until it has, it puts no key on any host by itself, so it never writes to a teammate's account it does not know of yet. It goes once iCloud has been read. If it stays, see iCloud is not syncing.

iCloud is not syncing#

The iCloud section of Settings — in This Device on the Mac, near the end of Settings on the iPad and iPhone — says how syncing stands:

• Off: Sync Through iCloud is off. Turn it on.
• Not signed in to iCloud: sign in to iCloud in the system's settings, with the same Apple Account on each of your devices.
• Syncing… or Up to date, with the time: syncing works. Sync Now fetches and sends at once rather than waiting for iCloud to say something changed.
• Any other sentence, in red, is what iCloud answered; it often clears by itself, or with Sync Now.
• "This build of SpectaShell is not signed for iCloud." means this copy of the app cannot reach iCloud at all.

Hosts, groups, snippets, triggers and trusted host keys sync; passwords and the device's keys never do. See Your devices, keys and iCloud.

A host will not keep shells#

A host that keeps shells needs a keeper of its own system. When it cannot have one, the pane says "Could not connect to host" with the reason:

• "SpectaShell has no keeper for … on …": the host's system or processor has no keeper. Keepers are made for Linux and macOS, on x86-64 and ARM64. Choose Stop Keeping Shells in the host's menu, or Plain Shells under Shells in Edit Host, and connect again: its shells are then plain, and end with their connection.
• A keepers' folder "owned by uid …, not by the current user", or one that "must not be accessible to group or others": on a shared server, someone else made the folder first (/tmp/spectashell-<your uid> on Linux). Anyone who could reach it could type into your shells, so no keeper starts there. Set SPECTASHELL_RUNTIME_DIR on that host to a folder of your own, which only you can open, or ask its administrator to remove the other one.

Kept shells are gone#

A pane whose shell was found gone says how it ended: "This shell on host was closed" with the device and the time, "Its program exited with code …", or "Its keeper stopped without a word: it was killed, or host shut down."

• After the host restarted, the pane says "host restarted, and this shell ended with it". Reopen starts a new shell in the same folder, and types the command that resumes a coding agent where it was. See Shells that keep running.
• Gone each time you log out of the host, without a restart: on Linux, systemd's KillUserProcesses=yes ends every process of a user whose last login ends, keepers among them, as it ends tmux. Its administrator can turn it off in /etc/systemd/logind.conf.

Notifications from hosts do not come#

Open Settings ▸ Notifications on the device that should hear them. Under Notify This Device it says what stands in the way:

• "Notifications are off for SpectaShell.": turn them on where it says — on the Mac, System Settings ▸ Notifications ▸ SpectaShell; on the iPad and iPhone, Settings ▸ Apps ▸ SpectaShell ▸ Notifications.
• This Device: Waiting for Apple…: the device has not yet been confirmed through Apple. It is tried again the next time SpectaShell starts.
• A host's name, with a reason: SpectaShell could not write that host's file for your devices. It tries again the next time one of your devices opens a shell there.

Otherwise:

• A host notifies once one of your devices has opened a shell there since you turned notifications on, and only from shells in its keepers; a plain SSH shell sends nothing.
• Your Mac's own shells notify once the Mac is one of your hosts, under your own user name, and one of your devices has connected to it (see No local shell).
• Shells started before then, by a keeper from before notifications existed, do not notify; start them again.
• Nothing is sent while one of your devices is in front: a Mac counts until it is locked, asleep or untouched for as long as The Mac Is Away says (see When you are away).
• A bell, a trigger's match and a connection that ended never come from a host.

The Mac's local shell will not start#

The pane says "Could not start the shell", with the reason. A local shell runs in a keeper, which keeps its sockets in ~/Library/Application Support/SpectaShell/keepers; a folder there that is not yours alone stops it, as on a host. Open a new tab to try again. If it fails again, the reason is what to send (see Reporting a problem).

When the pane says "The connection to this shell's keeper ended", Reconnect takes the shell up again.

A page will not load#

A page beside a shell, or one opened from a port, loads through a port forward. When the forward is not running, the page says why instead, under the host and port:

• "The forward of port … stopped.": the forward the page uses is no longer there, for example after it was stopped in Port Forwarding.
• "Port … could not be opened here.", or the reason the forward gave.

Try Again holds the forward again and loads the page. On an iPad or iPhone, forwards run only while SpectaShell is on the screen: a page opened in Safari outside SpectaShell stops loading, so use Open in Browser, which opens Safari inside it. When the forward runs and the page is still empty, check that the program on the host is running and listens on that port. See Files, ports and pages.

Reporting a problem#

When you report a problem, include:

• what you did, what you expected, and what happened, with the exact words the pane or a dialog showed;
• for a connection, its log: Show Logs, then Copy, and paste it into your report. Read it first: it holds the host's address, your user name, key fingerprints and what the host printed at login, but no password;
• the device, its system version, and SpectaShell's version (on the Mac, SpectaShell ▸ About SpectaShell);
• for a host, its system (uname -sm), and whether it keeps shells.