Skip to content

Troubleshooting

Jump to bottom
Mehdi edited this page Sep 3, 2026 · 8 revisions

Troubleshooting

Solutions to the most common issues with SSH Pilot.

For broader “how does this work?” questions, see the FAQ.

Connection Issues

Connection fails but ssh user@host works in the terminal

This is usually the graphical password dialog (Askpass) failing to display.

How to fix:

  1. Open a terminal and run SSH Pilot in verbose mode: 
    sshpilot --verbose
  2. Try connecting to the failing server
  3. Look at the log output for lines starting with ASKPASS: -- they will tell you why it failed

You can also check the askpass log directly:

cat $XDG_RUNTIME_DIR/sshpilot-askpass.log

Common causes:

  • Wayland/X11 environment variables not passed to the daemon
  • Display server not available

"Host key verification failed"

The server's host key has changed or is not yet trusted.

How to fix:

  1. Open the Known Hosts Editor (application menu → SSH → Known Hosts Editor, or Omni-search known hosts)
  2. Search for the old entry for that server
  3. Remove it and click Save
  4. Try connecting again -- SSH Pilot will ask you to accept the new key

Full details: Known Hosts.

Connection is slow to establish

If the first connection is slow but subsequent ones are fast, SSH multiplexing may help:

  1. Open Settings > SSH Options
  2. Enable SSH Multiplexing (ControlMaster)
  3. Connections after the first one will reuse the existing connection and open instantly

Terminal Issues

Text expander (Espanso, etc.) does not work

SSH Pilot captures keyboard shortcuts before they reach the terminal. This can interfere with text expanders.

How to fix:

  1. Go to Settings > Terminal > Keyboard
  2. Enable Terminal Shortcut Pass-through

This disables all SSH Pilot keyboard shortcuts and passes keys directly to the terminal.

Function keys (F10, F9, etc.) do not work in remote programs

Some programs like htop (F10) and mc (F9) use function keys that SSH Pilot may capture.

How to fix:

  • F10 -- Not bound by SSH Pilot. GTK's default accelerator is cleared, so F10 should work.
  • F9 (sidebar, or Cmd+B on macOS) and F11 (fullscreen) -- Unassign them in Settings > Shortcuts or enable Terminal Pass-through mode.

Terminal looks different from my regular terminal

SSH Pilot uses its own terminal settings. To match your regular terminal:

  1. Go to Settings > Terminal > Appearance
  2. Choose the same font you use in your regular terminal
  3. Pick a matching color scheme

SSH Config Issues

Changes to ~/.ssh/config are not showing up

SSH Pilot watches your SSH config through its daemon. External edits are usually picked up automatically after a short debounce. If the sidebar still looks stale:

  1. Wait a moment and check again, or
  2. Close and reopen SSH Pilot, or
  3. Connect once -- the next connection attempt uses the refreshed config

Hostname shows a different IP than expected

SSH Pilot uses ssh -G <hostname> to resolve the actual connection details. This is the definitive source.

To check what OpenSSH resolves:

ssh -G your-hostname | grep hostname

If this shows a different result than expected, the issue is in your SSH config, not SSH Pilot.

File Manager Issues

Permission denied in the SFTP file manager

The file manager uses the permissions of the user you connected as. If you connect as a standard user, you cannot modify system files (/etc/, /var/, etc.).

Workaround:

  • Connect as a user with the right permissions, or
  • Use the terminal tab with sudo for privileged operations

SFTP connection times out

If the SFTP connection drops or times out on slow networks:

  1. Open Settings > File Management
  2. Increase the SFTP keepalive interval (e.g., 30 seconds)
  3. Increase the SFTP connection timeout (e.g., 60 seconds)

Docker Console Issues

"Cannot connect to Docker daemon"

  1. Make sure Docker (or Podman) is running: 
    systemctl status docker
  2. For Local in Docker Console, confirm the CLI works on this machine: docker ps or podman ps
  3. Make sure your user is in the docker group: 
    groups
    Look for docker in the output. Or enable the sudo toggle in the Docker Console header.

"Permission denied" when managing containers

Add your user to the docker group:

sudo usermod -aG docker $USER

Then log out and back in. Alternatively enable sudo in the Docker Console header.

On Flatpak Local, Docker/Podman must be installed on the host OS (commands run via flatpak-spawn --host).

Backup Issues

Backup import fails

  • Make sure you are importing a backup made with the same or older version of SSH Pilot
  • Check that the backup file is not corrupted

Reporting Bugs

If you encounter a bug, please report it with diagnostic information:

Step 1 -- Generate diagnostics

Run SSH Pilot with the diagnostics flag:

sshpilot --diagnostics

This creates a .zip file containing sanitized logs (no passwords or private keys are included).

Step 2 -- Open an issue

Go to GitHub Issues and:

  1. Describe the problem
  2. Attach the diagnostics .zip file
  3. Include your OS and SSH Pilot version

Getting Help

Next Steps

Clone this wiki locally