Troubleshooting

Each problem below starts with what you see, then what it means and what to do.

The connection times out or is refused

The pane shows the server’s address and a reason such as “(timed out)” or “(Connection refused)”.

• Timed out: nothing answered within 15 seconds. Check the address and port, that the server is on, and that you’re on a network that can reach it (a VPN, for example). If the server is only reachable through another one, set a jump host.
• Connection refused: the machine answered, but nothing is listening on that port. SSH may be on a different port (check Port on the host), or the SSH service may be stopped.
• Name or address not found: the hostname doesn’t resolve. Check the spelling, or use the IP address.

Try the same address with ssh -p 22 [email protected] from a terminal on the same computer. If that fails the same way, the problem is between your computer and the server, not in Vaulterm.

Sign-in fails

You see	What to do
That username or password didn’t work.	Check the username and password. A saved password may be out of date: edit the identity and type the new one.
A message ending “Check the username and the key or password in this host’s identity.”	The server refused every way Vaulterm tried. Check the username, and that the key’s public half is in that user’s ~/.ssh/authorized_keys. See Put the public key on a server.
Your agent’s keys aren’t tried	On a Mac, check that ssh-add -l in Terminal lists your keys; add them with ssh-add. On Linux, check echo $SSH_AUTH_SOCK in the terminal you started Vaulterm from, and ssh-add -l lists your keys. On Windows, check the OpenSSH Authentication Agent service is running, or Pageant is open.

Servers allow a limited number of sign-in attempts, often 6. If your agent holds many keys, the server may give up before the right one. Give the host an identity with the right key instead.

On the server, sudo journalctl -u ssh -n 50 (or sshd, depending on the system) shows why it refused, which usually settles it.

“The server’s host key has changed”

Vaulterm stopped because the server’s key isn’t the one it trusted before. That’s expected after a reinstall, and a warning sign otherwise. Find out which before doing anything, then follow When a key changes.

“This host’s jump hosts loop back on themselves.”

A host’s jump host goes through the host itself, directly or through others. Open the host, and each of its jump hosts in turn, and fix Jump host under More options so the chain ends somewhere.

A session keeps saying it’s reconnecting

“Connection lost (…). Reconnecting in 8 s, attempt 4 of 10.” means the connection dropped and Vaulterm is trying again. After 10 tries it stops.

If it happens often on a good connection, something between you and the server is closing idle connections faster than Vaulterm’s 15-second keep-alive. That’s rare; check the server’s ClientAliveInterval and any firewall or load balancer timeouts in between.

Use tmux or screen on the server for anything that must survive a dropped connection: a reconnect gives you a new shell.

A transfer says it’s waiting for the connection

The terminal’s connection dropped. The transfer carries on by itself once Vaulterm reconnects. If the session ended for good, reconnect the pane and start the transfer again; Resume continues from where it stopped.

Other file messages:

You see	What it means
It no longer exists. Refresh to see the latest.	Someone deleted or moved it on the server.
A file called nginx.conf already exists.	Pick another name, or use Replace on the upload.
Didn’t upload id_ed25519: files from key and credential folders can only be uploaded with Upload files.	You dragged a file from a folder like ~/.ssh. Use Upload files if you meant to.
You don’t have permission to do that.	The user you signed in as can’t read or write there. Use the terminal with sudo for files you need root for.

A tunnel won’t start

You see	What to do
The address or port is in use	Something on this computer already listens on that port. Pick another, or port 0 for any free one.
This host needs you to sign in. Connect to it in a terminal first, then start the tunnel.	The host asks for a password or code, and a tunnel on its own can’t answer. Open a terminal to the host, then start the tunnel.
The connection to this host ended. Start the tunnel to connect again.	Start it again.
Tick the box to let other devices use this tunnel, or listen on 127.0.0.1.	You set Listen on to a network address. See Share a tunnel on your network.

A Remote tunnel that listens on the server but can’t be reached from other machines is usually the server’s GatewayPorts setting.

A tab doesn’t name the program on a server

Vaulterm finds the program in front of your shell by a variable it sends with the session, LC_VAULTERM_PANE. Debian and Ubuntu servers accept LC_* variables as they come; many others drop them, and then the tab and the Agents page only know what programs put in their window titles.

On a server you run, allow the variable in /etc/ssh/sshd_config:

AcceptEnv LC_VAULTERM_PANE

Reload the SSH server and open a new tab to it. Or turn on shell integration for the host, which reports each command in bash and zsh on any server.

The AppImage won’t start

• Nothing happens when you double-click it: make it executable (chmod +x Vaulterm-<version>.AppImage) and run it from a terminal to see the error.
• An error about libfuse.so.2: install FUSE 2 (sudo apt install libfuse2t64 on Ubuntu 24.04, libfuse2 on 22.04).
• An error about the sandbox or chrome-sandbox: your system blocks unprivileged user namespaces (Ubuntu 24.04 does by default for unknown apps). Install the .deb instead, which sets this up, or run the AppImage with --no-sandbox.

An update won’t install

You see	What to do
Couldn’t reach the update server. Vaulterm will try again later.	Nothing. It tries again later.
This update couldn’t be verified and wasn’t installed.	Don’t install updates for Vaulterm from anywhere but the download page. Tell us: the contact address is on the FAQ.
The download was damaged and has been deleted. Vaulterm will try again later.	Nothing. It downloads again at the next check.
.deb or .rpm: nothing happens after Restart to update	The update asks for your admin password. Check for a password prompt behind other windows.

“Vaulterm’s core stopped. Restart Vaulterm.”

The part of Vaulterm that holds the vault and runs connections stopped unexpectedly. Quit Vaulterm and open it again. Your vault isn’t affected. If it keeps happening, tell us what you were doing when it did, with the version and build from Settings → About.

You forgot your master password

Use your Recovery Key: on the lock screen, press Forgot your password? Use your Recovery Key. See If you forget your password.

“Your vault file is damaged or was modified outside Vaulterm.”

Something changed vault.db other than Vaulterm: a disk problem, a sync tool, or someone editing it. Vaulterm won’t use it. Quit Vaulterm and restore a backup of vault.db. See Back up the vault.

Don’t keep vault.db in a folder that a sync tool (Dropbox, OneDrive, Syncthing) writes to while Vaulterm is open. Copy backups there instead.

Still stuck

Read the FAQ, or write to us at the address there. Include:

• the version and build (Command Center: Copy version and build),
• your system (macOS 15, Windows 11, Ubuntu 24.04 and so on) and how you installed Vaulterm,
• what you did, what you expected, and the exact message.

Never send your vault file, Recovery Key, passwords or private keys. Nobody at Vaulterm will ever ask for them.