Troubleshooting

This page lists common problems by area, with the message the app shows where there is one and the steps that resolve it.

Connections

Connection refused

The host answered, but nothing is listening on the port.

1. Check that the SSH daemon runs on the server: sudo systemctl status sshd (the unit is ssh on Debian and Ubuntu).
2. Check the port in the server’s settings. SSH defaults to 22.
3. Check the server’s firewall: sudo ufw status or sudo firewall-cmd --list-all.

Connection timed out

The host did not answer at all.

1. Check the host name or address, and that the machine is on the network.
2. Check cloud security groups and network firewalls between you and the server.
3. If the server’s address changed (DHCP on a home network), open the server sheet and use Scan network for its new IP. It recognizes the server by its pinned host key and updates the address. This requires Pro.
4. On slow links, raise SSH Connect Timeout under Settings › Connection. The default is 10 seconds.

Authentication failed

1. Use Test Connection in the server’s settings. It runs the real login, including keyboard-interactive prompts for two-factor codes, and reports the specific error.
2. For password logins, check the username and password. Both are case-sensitive.
3. For key logins, check that the right key is selected and that its public key is in ~/.ssh/authorized_keys on the server.
4. Check that /etc/ssh/sshd_config allows the method you use (PubkeyAuthentication yes, PasswordAuthentication yes or KbdInteractiveAuthentication yes for two-factor prompts).

Host key changed

When a server presents a different host key from the one PocketCmd pinned, the connection stops and the app shows Host key changed with both fingerprints. If you know the server was reinstalled or its keys were regenerated, compare the new fingerprint with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server and choose Trust new key. If nothing changed on the server, do not accept the key: the connection may be intercepted.

Server is paused

This server is paused means the server is over the Free plan’s limit of one active server. It stays saved and grayed out but does not connect, not even as a jump host for another server (Its jump host is paused). Make it the active server or upgrade to Pro. Sessions that were already running when Pro ended keep their connection until you close them, and SFTP transfers to a paused server pause and resume when it is active again. See Free and Pro.

Mosh, Eternal Terminal and Telnet

“Mosh unavailable, using SSH”

Mosh and ET sessions start with an SSH login that launches the remote server process. If that fails, the session falls back to a plain SSH shell and shows Mosh unavailable, using SSH (or ET unavailable, using SSH).

• Mosh: mosh-server must be installed on the host, and UDP ports 60000–61000 (mosh-server’s default range) must be open to your device.
• ET: etserver must be installed and running, and TCP port 2022 must be reachable.

The server sheet’s protocol check names the missing piece: No Mosh: mosh-server is not installed., No ET: etserver is not installed. or No ET: etserver is not running.

Telnet warning appears every time

The unencrypted-connection warning is stored per server. Check Don’t show again for this task in the dialog. A deleted and re-created server asks again.

Telnet auto-login does nothing

Auto-login answers a prompt line that ends in login: or username:, then a short prompt line such as Password:. Devices with other prompts need a manual login: clear the saved username and password, or change the prompt on the device.

Wrong terminal size over Telnet

PocketCmd reports the window size through the Telnet NAWS option. Older Telnet servers ignore it; set the size on the remote side with stty rows <n> cols <n>.

SSH keys

“Invalid key format”

1. Import the private key. A public key is one line starting with ssh-ed25519, ssh-rsa or ecdsa-sha2-; a private key starts with -----BEGIN.

2. If the key was pasted from email or chat, check that the -----BEGIN and -----END lines and the line breaks survived.

3. Check the format against Supported Key Formats. DSA keys are not supported; generate an Ed25519 key instead:

   ssh-keygen -t ed25519 -C "[email protected]"

The key asks for a passphrase you never set

Check the file on a computer. ssh-keygen -y -f <key> prints the public key without a prompt when the key is not encrypted. If it prompts, the key is encrypted. If it fails, the file is damaged; export or generate the key again.

SFTP

When the server refuses a file operation, the message explains the SFTP status code and keeps the number at the end, for example … (SFTP error 3).

Code	Meaning
1	End of file reached before the expected data.
2	The file or folder does not exist.
3	Permission denied for your account on the server.
4	The server gave no reason. Common causes: the name already exists, the folder is not empty or the disk is full.
5	The server rejected the request as invalid, for example a name that is too long.
6, 7	The connection was lost.
8	The server does not support the operation.
9	The server no longer recognizes the open file. Try again.
10	A folder in the path does not exist.
11	A file or folder with that name already exists.
12	The location is read-only.
13	No storage medium at that location.
14	The server’s disk is full.
15	Your storage quota is used up.
16	The server does not recognize the owner or group.
17	Another process holds a lock on the file.
18	The folder is not empty.
19	The path is a file, not a folder.
20	The server does not accept the file name.
21	The path runs into a loop of symbolic links.

Most servers (OpenSSH among them) report only codes 1 to 8, so code 4 covers many specific causes.

Transfers of many small files are slower than one large file. Pack them first (tar czf archive.tar.gz dir/) and transfer the archive.

PocketCmd Pro and licenses

Message	What to do
This key is in use on 3 devices	A license key covers three devices. Free a slot on another device with Deactivate this device, or free one from this device when the app offers it.
This key has already been moved between devices 3 times in the last 30 days.	Slots can move three times in 30 days. The message says when the next move is possible.
Couldn’t confirm your license. Pro is paused until PocketCmd reaches the license server.	The app checks a license key once a day and keeps Pro for up to 7 days after the last successful check. Connect to the internet and refresh; Pro returns by itself after a successful check.
Purchases are unavailable right now	Sign in to the App Store or Google Play on the device, then try again.
A store purchase does not unlock Pro	Use Restore purchases in Settings › PocketCmd Pro. The app verifies the store’s signature before Pro counts.
Your subscription has ended.	Renew the subscription. Nothing created while you had Pro is deleted.

Background sessions

iOS disconnects after a while in the background

iOS suspends apps shortly after they leave the screen, so PocketCmd cannot hold connections open in the background. Mosh and Eternal Terminal sessions are saved before suspension and restored when you return. SSH and Telnet connections drop and reconnect with a new shell; run tmux on the server to keep your work across that. See Session Management.

Android drops connections in the background

1. Check Settings › Connection › Keep Alive Service. Its categories decide what is protected in the background: terminal connections, SFTP connections, SFTP transfers and port forwardings. Disabled categories disconnect when the app goes to the background; Mosh and ET reconnect by design.
2. On Android 13 and later without notification permission, the service still runs, but its notification appears in the system’s active-apps list instead of the notification shade.
3. Set PocketCmd’s battery usage to Unrestricted in the Android app settings. Some manufacturers stop background apps aggressively; see dontkillmyapp.com for device-specific steps.

Dashboards

A card shows no data or an error

1. For a card that runs an SSH command, run the same command in a terminal on that server and check that it prints a number.
2. For a card that shows a server metric, check that a PocketCmd Server is paired, that you have Pro and that your team role includes View metrics. The server has no built-in metrics: if the card editor lists none, no metric command has been approved on that server yet. Request one under Metric requests in the team.
3. A dashboard over the Free limit is read-only and is not refreshed.

Values do not update on the home screen

The home screen never opens an SSH connection. SSH-command cards in the dashboards strip show their last stored value; open the dashboard to poll them. The refresh countdown in the dashboard’s toolbar shows the interval: tap it to cycle presets, long-press it for a custom value. Local history goes back as far as Metric history retention under Settings › Data.

Alerts

No alert notifications arrive

Alerts are evaluated by the PocketCmd Server, not on the phone. Check in this order:

1. You are on a phone or tablet. The desktop apps do not receive push notifications.
2. Notifications are allowed for PocketCmd in the system settings. A device registers for push only after you allow them; see Push notifications.
3. Your team role includes Receive alerts.
4. The rule is not inside its quiet period: a continuing breach notifies at most once an hour, and a rule never notifies twice within 10 minutes.

Import and export

The backup password is rejected

Every backup has its own 32-character password, generated by the app and shown once when the backup was created. Enter that password exactly, ideally by pasting it from where you stored it. A password from a different backup does not work, and a lost password cannot be recovered. Files over 50 MB are refused as damaged or not PocketCmd backups.

Imported items are missing

• A server whose ID already exists on this device is skipped, so importing the same backup twice adds nothing.
• An SSH key whose backup entry has no private key is skipped, and the import reports its name.
• On the Free plan, servers past the limit are imported grayed out and you choose which one stays active.

PocketCmd Server

pcmd not found after installing

The install script uses /usr/local/bin, or ~/.local/bin when it cannot write there, and warns if the directory is not on your PATH. Add it (export PATH="$HOME/.local/bin:$PATH") or run the binary by its full path.

The QR code stopped working on the first run

Each pairing code is valid for 60 seconds. The first run prints a new code when the old one expires, so scan the most recent one. After five minutes without a pairing, the command exits with pairing timeout and saves nothing; run pcmd again to start over.

A new device can’t pair with the server’s QR code

Only the first run’s code pairs a new device, and only while the server has no team yet. The code printed by pcmd rotate-server-cert re-pairs devices the server already knows. To add a device or a person to an existing server, create an invite with pcmd invite or from the app, and join with Teams › Join a team.

pcmd refuses to run as root or under sudo

On systemd and macOS the service is installed per user, and its data lives in that user’s ~/.pocketcmd. Log in as the user who should own the server and run pcmd without sudo. Only OpenRC, which has no per-user services, needs sudo pcmd install.

The service did not install, or stops after logout

1. systemd: check pcmd status and systemctl --user status. A user service stops when you log out unless lingering is on: loginctl enable-linger $USER. pcmd status shows whether it is.
2. OpenRC: installing writes to /etc/init.d and needs sudo pcmd install. The service then runs as your user.
3. No init system (minimal containers): run pcmd --foreground under your own supervisor.
4. pair a device first: pcmd install refuses until a device has paired. Run pcmd and pair first.
5. After fixing the cause, run pcmd install.

The app shows “Incompatible server”

The server speaks a different API version than the app, so the app stops talking to it. The message names both versions. Install a matching server with the command the app shows under Teams › Set up a new server (it passes the app’s version as --api), or update the app. See Versions and compatibility.

The app shows “Needs re-pair”

The server no longer accepts this device. After pcmd rotate-server-cert, scan the re-pair code it printed. If the device was removed from the team, join again with an invite.

Server fingerprint mismatch

The server’s certificate changed after the device paired, because of pcmd rotate-server-cert, a reinstall that lost ~/.pocketcmd/tls/ or a restore from another machine’s backup. Scan the re-pair code that pcmd rotate-server-cert prints; if you no longer have it, run the command again. If the server lost ~/.pocketcmd entirely, it no longer knows the device: remove the server in the app and set it up from scratch.

For pairing problems in the app, see QR Code Pairing.

Performance

The terminal feels slow

1. Lower Scrollback Lines under Settings › Terminal (1,000 to 50,000, default 10,000).
2. Set Animated Background to None under Settings › Appearance.
3. Each jump host adds a round trip to every keystroke over SSH. Mosh’s local echo hides latency on slow links.
4. Check the network: packet loss and high latency show up as typing lag.