How Conn tells you
Each problem comes in three parts: what happened, why, and what to try. Where the machine said something itself, an i button labelled Details (or What the server said) shows its own words. In the messages below, Home Lab stands for your host's name.
If a message doesn't help, email us its words exactly, or a screenshot, with your Conn version (Settings, About) and what the machine runs. See Support.
A machine doesn't answer
These appear on a host's tile, its page and in Test Reachability, which tries every address on every port the host uses.
| Tile says | Message | What it means and what to do |
|---|
| Port closed | Nothing is listening on port 22 at Home Lab. | The machine is up, but the service isn't running, or it uses another port. On a Mac, turn on Remote Login (or Screen Sharing) in System Settings, General, Sharing. Elsewhere, start the SSH or VNC server. If it listens on another port, change the port in Edit Host. |
| Not reachable | Conn could not reach Home Lab. | Nothing on the network answered: the machine is asleep, off, or on a network this device can't see. Wake it, and if you reach it over a VPN, connect the VPN first. An unanswered .local name also reads this way. |
| Name not found | Conn could not find Home Lab. | The name didn't turn into an address. A .local name works only on the same network, and a Tailscale name only while Tailscale is up. Check the spelling, or use the IP address. |
| No answer | Home Lab did not answer in time. | Nothing answered within 4 seconds. Check it's awake; a busy or distant machine may need another try. |
| No network | This device has no network connection. | Join Wi-Fi, connect Ethernet or turn off Aeroplane Mode. |
| Needs permission | Conn is not allowed to use the local network. | Turn on Local Network for Conn: on iPhone and iPad in Settings, Privacy & Security, Local Network; on a Mac in System Settings, Privacy & Security, Local Network. Machines reached over a VPN or a public address work without it. |
| Screen only (or another panel) | Screen answers on Home Lab. Nothing is listening on port 22. | One service answers and the other doesn't. Turn on the missing one, or turn it off for this host in Edit Host, Connections. |
- An old Tailscale name ending in
beta.tailscale.net can't resolve anywhere any more. Use the machine's .ts.net name from the Tailscale admin console.
- Screen port open to the internet, in Test Reachability, means anyone can try that screen's password. Close the port on your router, and use Tailscale or SSH instead.
SSH connection messages
| Message | What it means and what to do |
|---|
| Remote Login is off on Home Lab. | A Mac turned the connection away. Turn on Remote Login in System Settings, General, Sharing. |
| Home Lab refused SSH. | Nothing is listening on the SSH port. Start the machine's SSH server, or check the port in Edit Host. |
| Conn could not reach Home Lab. | The network has no way to the machine right now. Try again when this device's network can reach it. |
| Conn gave up waiting for Home Lab to answer. | Nothing came back in time (10 seconds to connect, 20 to set up). Try again; a far-away or slow machine may need another go. A name that can't be found can look like this too. Later steps read "Conn gave up while signing in to Home Lab" and so on. |
| Home Lab stopped responding. | The connection was open and the machine stopped answering, which is what a dropped network looks like. Check this device's network. A tmux terminal picks the session back up on its own. |
| Home Lab closed the connection. | The machine ended it, sometimes saying why. The machine isn't necessarily down. If it keeps happening at once, check the machine's SSH server log. |
| Conn and Home Lab could not agree on the cryptography for the connection. | They share no method to encrypt with. Often the machine offers only an RSA host key, which Conn can't use yet. Most servers also have an Ed25519 one (/etc/ssh/ssh_host_ed25519_key); if yours doesn't, sudo ssh-keygen -A makes any that are missing, then restart its SSH server. ssh -v from a computer names the method that didn't match. |
| Home Lab refused to start the session. | Signing in worked, but the account isn't allowed a shell, or is limited to file transfer. Check the account on the machine. |
| The terminal on Home Lab has already ended. | The shell exited. Open a new terminal; anything typed after it ended wasn't sent. |
| The connection to Home Lab went wrong in a way Conn did not expect. | Not something you did, and not a password problem. If it happens every time, send us the details. |
Signing in
| Message | What it means and what to do |
|---|
| Home Lab did not accept the sign in. | The user name, password or key was refused. Conn can't tell a wrong password from a user name the machine doesn't have. Check the user name, the password, or that the key's public half is in ~/.ssh/authorized_keys on the machine. If the machine names no method Conn understands, it probably wants keyboard-interactive or two-factor sign in, which Conn can't do yet. |
| Conn could not use the key. | The key is a kind Conn can't sign with, such as RSA. Pick another key, or make one in Keys. |
| The password for admin is not saved on this device. / The key Home Lab uses is not on this device. | The sign in was saved on another device. Enter the password or choose a key once here. See On your other devices. |
| Conn does not know how to sign in to Home Lab. | No user name and password or key is saved. Add a sign in in Edit Host. |
| Conn cannot use that sign in for SSH. | The saved sign in is a screen's password, not an SSH one. Add an SSH password or key to the host. |
Server keys
| Message | What it means and what to do |
|---|
| The identity of Home Lab has changed. | The machine's SSH key isn't the one Conn kept. If you rebuilt or reinstalled it, choose Replace the Stored Key when Conn asks. If not, don't connect: check the machine from somewhere you trust. See When a key changes. |
| Home Lab proved its identity a different way this time. | It offered a different kind of key. Compare the fingerprint on the machine (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub) before choosing Record This Key Too. |
| Conn did not connect to Home Lab. | A connection Conn made by itself met a key it has no record of, so it stopped. Connect yourself once to answer. |
| Conn could not check the identity of Home Lab. | The machine offered a certificate, which Conn doesn't accept. Use the machine's plain host key. |
| Home Lab closed the connection while you were deciding. | SSH servers allow a fixed time to sign in. Connect again; the same question is asked. |
Face ID, Touch ID and saved passwords
| Message | What it means and what to do |
|---|
| Conn did not unlock the saved password for Home Lab. | The Face ID or Touch ID prompt was cancelled. Try again and approve it. |
| Conn could not unlock the saved password for Home Lab. | The check didn't recognise you. Try again. |
| This device cannot check who you are. | Face ID or Touch ID isn't available right now. Check it in Settings, or use Use Once. |
| There is nothing set up for this device to check against. | No face or fingerprint is set up. Set one up, or a passcode. |
| This device has no passcode. / This Mac has no login password. | Saved passwords need one. Set a passcode (or a Mac login password). Use Once works without one. |
| Conn could not read a saved secret. | The device was locked when Conn asked. Unlock it and try again. |
| Conn could not unlock … without asking you again. | The system wanted a second check part way through, the device locked, or Conn wasn't in front. Unlock and try again. |
| Conn has no saved secret for Home Lab. | The host is saved but its password isn't. Enter it or pick the key again. |
Terminal
| Message | What it means and what to do |
|---|
| This session has ended | The banner says why: the shell exited, the host closed it, or the connection went. Press Reconnect. With tmux, you're put back in your session. |
| Anything you typed in the last few seconds may still reach the host. | Typing just before a dropped link can arrive late. Conn never sends it again, so check the host before retyping. |
| Some typing did not reach Home Lab | The link went before it was sent, and Conn won't send it again. |
| No tmux on Home Lab | The host has no tmux, so this is a single session. Press Install tmux, or install it yourself. |
| tmux did not start / tmux gave an error | What the shell printed is on screen. Press Attach to try again where your session may still be. |
| Home Lab's tmux cannot be used / The tmux on Home Lab is too old | Conn needs tmux 2.1 or later. Update tmux on the host. |
| Conn could not check for tmux | The host didn't answer the check in time. Open the terminal again. |
| Conn types only at the shell's prompt. | Finish or quit what's running, then press the button again. |
| Paste and run 3 lines on Home Lab? | The paste has line breaks and the program isn't expecting a paste, so each line would run. Paste only if that's what you want. |
| Home Lab wants to copy to this device. Allow? | A program on the host asked to put text on your clipboard. Allow only hosts you trust. |
Screen
| Message | What it means and what to do |
|---|
| Nothing is listening on port 5900 at Home Lab. | Screen sharing isn't on. On a Mac, turn on Screen Sharing; on a Raspberry Pi or Linux, start the VNC server. If it uses another port, set Port on the machine in Edit Host, Screen. |
| The screen is not answering over SSH on Home Lab. | Conn signed in over SSH, but nothing answered on the screen's port on the machine. Turn screen sharing on, and check Port on the machine. |
| Home Lab does not let a screen go over SSH. | Its SSH server doesn't allow forwarding. Set AllowTcpForwarding yes in sshd_config, or set the host to connect directly. |
| Home Lab did not offer a sign in Conn can use. | It offered only methods such as VeNCrypt or TLS. Turn on password or RSA-AES sign in on the VNC server; on a Mac, turn on Screen Sharing. |
| Home Lab did not accept that password. | The VNC password is wrong. VNC uses only its first 8 characters. |
| Home Lab did not accept that name and password. | One is wrong, or the account isn't allowed to use Screen Sharing. On a Raspberry Pi, use the account signed in at its desktop. |
| That name or password is too long for Home Lab. | A Mac takes up to 63 bytes (most letters are one byte); other screens 255. |
| Signing in to Home Lab did not finish. | The screen stopped answering part way. A Mac may be waiting for someone at it to accept. |
| Home Lab did not answer. | Nothing came back from the screen in time. Check screen sharing is on. |
| Conn could not start a screen session on Home Lab. | Something answered on the screen's port, but not as Screen Sharing or a VNC server, or the screen refused. Check the port and the screen's settings. |
| Conn did not send the password. | The route was meant to be Tailscale, but this connection didn't go over it, so it wouldn't have been encrypted. Check how the screen goes now, then try again. |
| The screen key for Home Lab has changed | A screen that encrypts itself offered a different key. Check before you accept it. A reconnect that meets it says "Signing in to Home Lab could not be finished." |
| The screen on Home Lab is too large to show. | Over 16,384 pixels on a side, or more than this device can hold. Lower the resolution on that machine. |
| Conn could not read what Home Lab sent. | Part of an update didn't make sense, so Conn stopped rather than draw it wrong. If the i says the screen switched to a colour palette, set the VNC server to full colour. |
| The screen did not come back | Conn tried for 20 seconds after the link went. Press Reconnect when the machine is reachable. |
| The Mac may not have locked. | Lock on disconnect didn't finish before the screen closed. Connect again to check the Mac. |
Files
| Message | What it means and what to do |
|---|
| Files could not open on Home Lab. | See the reason under it. "Would not start its SFTP service" means the server's SFTP subsystem is off: check Subsystem sftp in sshd_config. |
| The account Conn signed in with is not allowed to do that here. | A permissions problem on the machine. Check who owns the item, or sign in as an account that may change it. |
| The folder still has items in it | A folder must be empty before it can be deleted. Empty it first. |
| There is already an item with that name in this folder. | Choose another name. Uploads never replace a file. |
notes.txt.conn-part, from another save or upload, is in the way. | A save or upload was cut off. Delete the .conn-part file on the machine, then try again. |
| The file notes.txt changed on the machine while you were editing it. | Something else wrote to it. Your typing is still on screen. Read Again loads the newer file in its place. |
| This file is too big for the editor. | Over 1 MiB. Download it, or work on it in a terminal. |
| Reading only | The file isn't plain UTF-8 text, is a link, or the server can't replace a file in one step. The i says which. |
| This download has to start from the beginning | The part already downloaded can't be continued. Press Start Again. |
| There is not enough space on this device for notes.txt. | Free some space on this device, then try again. |
| This folder has more items than Conn lists | Over 200,000 items. Work with it in a terminal. |
| The connection to Home Lab ended. It ended while Conn was away. | You signed in with a password or key Conn didn't keep, so it can't reconnect by itself. Press Sign In and Try Again. |
Jump hosts and port forwards
| Message | What it means and what to do |
|---|
| Conn could not get through Bastion on the way to Home Lab. | Something about the jump host stopped the connection, such as no saved sign in or an unknown key. Connect to the jump host on its own first. |
| The hop through Bastion failed, so the connection never reached Home Lab. | The connection got as far as the jump host and failed there; the reason under it is the jump host's. Open the jump host in Conn and check it connects on its own first. |
| The jump hosts on the way to Home Lab go in a circle. | A chain leads back to a machine already on the way. Fix Reach It Through in Edit Host for one of them. |
| The forward stopped. | The connection carrying it ended. On iPhone and iPad a forward runs only while Conn is open. Start it again. |
| Conn could not start this forward. | It has no machine or port to go to. Fix the forward in Edit Host. |
Finding machines on your network
| Message | What it means and what to do |
|---|
| Conn cannot look for machines on this network. | Local Network is off for Conn. Turn it on in your device's Privacy settings, or add machines by hand. |
| No machines found on this network | Nothing is announcing SSH or screen sharing. Turn on Remote Login or Screen Sharing on a Mac, or add the machine by its address. |
| Conn stopped looking for machines. | The system's discovery stopped. Try again, or add machines by hand. |
Still stuck?
Email admin@bottletopstudios.co.uk with the message's exact words or a screenshot, your Conn version (Settings, About), your device and its system version, and what the machine runs. Never send a password or a private key; we'll never ask for one.
