Troubleshooting
Error messages and fixes for SSH and storage connections, files, AI Pilot, kaiport Pro, updates and the app itself.
On this page
- Where to find error details
- SSH connections
- Connection errors
- Passwords, keys and the SSH agent
- Host keys
- Jump hosts
- Older servers and devices
- Dropped connections
- Storage connections
- Files and editor
- AI Pilot
- kaiport Pro
- App issues
- macOS asks for "kaiport Safe Storage"
- Linux: "Not available – secrets are only encoded"
- Saved credentials are asked for again
- Tabs are not restored
- Data folder and log file
- Updates
This page lists the messages kaiport shows when something goes wrong, what they mean and what to do. Messages are quoted as the English interface shows them; an ellipsis (…) stands for details that vary. If your problem isn't listed here, Support explains what to send us.
Where to find error details
- Terminal tabs: a failed or dropped connection shows Connection failed or Disconnected with the reason. You can select and copy the text. Reconnect tries again, Close tab closes the tab.
- Storage tabs (FTP, S3, WebDAV, Azure Blob): the transfer view shows "Connection failed: …", up to three Possible causes, Try again and AI diagnosis.
- AI Pilot: errors appear in the AI Pilot panel. In Settings → AI Pilot, Test connection checks your provider.
- Unexpected errors are written to
kaiport.login the data folder.
SSH connections
Connection errors
| Message | Cause | What to do |
|---|---|---|
| Connection refused (ECONNREFUSED). Is the SSH service running on that port? | The server answers, but nothing accepts connections on this port. | Check host and port (usually 22). Make sure the SSH service runs and the firewall allows the port. |
| Host not found (DNS lookup failed). | The host name cannot be resolved. | Check the spelling, or use the IP address. If the server is only reachable in a company network, connect to the VPN first. |
| Connection timed out. | The server didn't respond in time. | Check address and port. A firewall may drop the connection, or the server is down. |
| Host unreachable. | There is no network route to the server. | Check your network and VPN connection. |
| Authentication failed. | The server rejected every login method that was tried. | Check the username and the password or key. The server may not allow this method, for example password login. |
| Handshake failed: no matching … The server offers: … | The server and kaiport have no algorithm in common. | See Older servers and devices. |
| Connection not found. | The saved connection no longer exists, for example because it was deleted. | Open the connection again from the start window, or create it again. |
Passwords, keys and the SSH agent
| Message | Cause | What to do |
|---|---|---|
| Password required | The connection has no saved password. | Enter it. Select Store encrypted for this connection to save it. |
| Login failed: The password was not accepted. Please try again. | The password was wrong. You have three attempts. | Enter the right password. If a wrong one is saved, correct it in the connection. |
| Login | The server asks its own questions, for example for a one-time code. | Answer the questions in the dialog. |
| Passphrase required: The key … is encrypted. | The private key is protected and no passphrase is saved. | Enter the key's passphrase. You can save it encrypted. |
| Wrong passphrase | The passphrase didn't open the key. | Enter it again. |
| The passphrase was not accepted. | Three wrong passphrases. | Check the passphrase and connect again. |
| No private key configured. | The connection uses SSH key, but no key was chosen. | Edit the connection and choose the key with Choose. |
| Could not read key file: … | The key is only referenced by its path, and the file is missing or unreadable, for example after an import. | Edit the connection and select the key again with Choose. kaiport then keeps it in its encrypted vault. |
| Invalid key: … | The file is not a private key kaiport can read. | Use a private key in OpenSSH, PEM or PuTTY (.ppk) format. |
| No SSH agent found (SSH_AUTH_SOCK is not set). | The connection uses SSH agent, but kaiport sees no running agent (macOS and Linux). | Start an agent and add your key with ssh-add, then start kaiport from a session in which SSH_AUTH_SOCK is set. Or use SSH key. |
| Connection cancelled | You closed a password, passphrase or login dialog. | Click Reconnect. |
On Windows, kaiport uses the agent of the OpenSSH client built into Windows (\\.\pipe\openssh-ssh-agent). In Services, set OpenSSH Authentication Agent to start automatically and start it, then add your key with ssh-add. See SSH agent. The Mac App Store version has no SSH agent; use SSH key there.
Host keys
kaiport checks the host key of every SSH server against its list of known hosts. It keeps its own list, separate from ~/.ssh/known_hosts, so it asks once even for servers you know from other SSH clients.
- Unknown host appears the first time you connect to a server: "The authenticity of … cannot be established." Compare the fingerprint with the one of your server, for example with
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pubon the server, and click Trust if they match. - Host key has changed appears when a server presents another key than the stored one: "The host key of … has changed!" This happens when a server was reinstalled or got new keys, but it can also mean that someone is intercepting the connection. The dialog shows the new and the previously stored fingerprint. Click Accept new key only if you know why the key changed; otherwise click Cancel and ask the server's administrator.
- Host denied (verification failed): the connection ends like this when you click Cancel in one of these dialogs. Connect again to see the question once more.
- Host key was not accepted.: the host key check failed. Connect again and check the key in the dialog.
Settings → Known hosts lists the stored keys. Forget removes one, and kaiport asks again on the next connect. See Host key check.
Jump hosts
| Message | Cause | What to do |
|---|---|---|
| The configured jump host no longer exists. | The connection set as jump host was deleted. | Edit the connection and choose another jump host under Advanced, or Connect directly. |
| Connection through jump host "…" failed: … | kaiport couldn't log in to the jump host, or the jump host couldn't reach the target. The second part names the reason, with the messages from the tables above. | Connect to the jump host on its own first. Check that the jump host can reach the target's host name and port. |
While it connects, the tab shows "Connecting through …". The jump host logs in with the password, key or agent saved in its own connection; kaiport doesn't ask for a password or a one-time code on the way. Save the jump host's password, or use a key or the agent. See Jump host.
Older servers and devices
kaiport prefers modern algorithms. For older servers, appliances and network devices, it also offers older ones as a last resort, such as CBC ciphers, hmac-sha1, diffie-hellman-group14-sha1 and ssh-dss host keys, so these usually connect without extra settings.
If a server offers none of the algorithms kaiport supports, the connection fails with "Handshake failed: no matching …", followed by "The server offers: …" and the server's list. The first part names the step, for example the cipher or the key exchange. Enable a newer algorithm on the server or device; the list shows what it offers today. See Older and hardened servers.
Dropped connections
"Connection ended", "Connection closed", "Session ended" and "Disconnected" mean that the server or the network ended the session, or that the shell on the server exited, for example after exit.
- Click Reconnect or press ⌘RCtrlR.
- With Settings → Terminal → Reconnect automatically (on by default), kaiport tries up to three times to reconnect a session that was connected, and shows "Retrying in …s". See Reconnect automatically.
Storage connections
When an FTP, S3, WebDAV or Azure Blob connection fails, the transfer view shows the message and up to three Possible causes that kaiport derives from it. AI diagnosis hands the message to AI Pilot, which explains what to change in the settings. Try again connects again.
| Connection | Possible cause | What to do |
|---|---|---|
| S3 | The signature does not match. | Check the access key and the secret key: no spaces, and the key pair of this provider. |
| S3 | The bucket lives in a different region than configured. | Set the region of the bucket, or look it up at your provider. |
| S3 | There is no bucket with this name at this endpoint. | Check the spelling of the bucket and the provider's endpoint. |
| S3 | Access denied. | The key has no rights on this bucket (check the policy or IAM), or the bucket name is wrong. |
| S3 | The host name with the bucket prefix cannot be resolved. | Turn on Path-style addressing. MinIO, Ceph and many providers need it. |
| FTP | Login rejected. | Check username and password. Some servers expect the user with domain, as in user@domain. |
| FTP | The data connection fails (passive mode). | A firewall or NAT blocks the data ports. Open the passive port range on the server. |
| FTP | The server requires encryption. | Set Encryption to FTPS explicit (AUTH TLS). |
| FTP | Port and mode do not match. | Implicit TLS uses port 990; explicit TLS and plain FTP use port 21. |
| WebDAV | Login rejected (401). | Check username and password. Nextcloud and ownCloud with two-factor sign-in need an app password. |
| WebDAV | The path does not exist (404). | Check the WebDAV address. For Nextcloud it ends in /remote.php/dav/files/USER/. |
| WebDAV | The server does not answer with WebDAV. | The URL probably points at the web interface instead of the WebDAV endpoint. |
| Azure Blob | Authentication failed. | Check the account name and the access key: the full base64 key, not a SAS token. |
| Azure Blob | The container does not exist. | Check the name, or leave Container empty to list all containers. |
| All | Connection refused. | Check host and port. Is the service running and the firewall open? |
| All | Timeout. | The host or port is wrong, a firewall blocks the connection, or the server doesn't answer. |
| All | The host name cannot be resolved. | Check the spelling. For S3, enter the endpoint without the bucket name. |
| FTPS, WebDAV | The certificate is self-signed or unknown. | If you trust the server, turn off Verify certificate. |
| All | The certificate belongs to a different host name. | Use the host name from the certificate as host. |
| All | The server rejects the credentials. | Check username, password or key. |
Other messages of storage connections:
| Message | What to do |
|---|---|
| Login rejected (401/403). Check user name, password or app password. | WebDAV refused the login; see the WebDAV rows above. |
| The server answered with HTTP … | The WebDAV server answered unexpectedly. Check the Server URL. |
| Path not found: … | The folder doesn't exist on the WebDAV server. Check the Server URL and the Remote start directory. |
| Buckets cannot be created here. / Buckets cannot be renamed. / Buckets cannot be deleted here. | kaiport works inside buckets and containers. Create, rename or delete them with your provider's tools. |
More about the settings of each type in Storage connections.
Files and editor
| Message | What to do |
|---|---|
| File is too large to open (max 2 MB). | The built-in editor opens files up to 2 MB. Download the file, or switch Settings → Editor to External to edit it in another editor. |
| Folders cannot be transferred. | Uploads take files, not folders. Select the files inside the folder, or pack the folder into an archive first. |
| No active session for file access. | The connection of this tab is closed. Reconnect and try again. |
| Saving failed: … | The editor couldn't write the file back, for example for lack of permission. The message names the reason. |
| Upload failed | An external editor saved the file, but uploading it failed. Check the connection; kaiport uploads again the next time the editor saves. |
AI Pilot
| Message | Cause | What to do |
|---|---|---|
| Set up an AI provider | No provider is set up yet, or the settings are incomplete. | Enter URL, token and model under Settings → AI Pilot and click Save. |
| No AI provider configured. Please set URL, token and model in the settings. | Same as above. | Same as above. |
| Test failed: … | The test request to the provider failed; the reason follows. | See the rows below. |
| Invalid API key (401). / HTTP 401: … | The API token is wrong, expired or belongs to another provider. | Paste the key again and check that the URL belongs to the same provider. |
| Rate limit reached (429) – please wait a moment. / HTTP 429: … | The provider limits your requests. | Wait a moment. Check your plan and credit with the provider. |
| API error …: … / HTTP …: … | The provider reports an error, for example an unknown model or missing credit. | Read the provider's message. Choose another model, or check your account with the provider. |
| Could not load models: … | The model list couldn't be fetched. | Check URL and token. If the provider has no model list, type the model name. |
| The model sent nothing for 120s – the connection was dropped. | The provider stopped sending. A local model may also be too slow or still loading. | Send the request again. |
| Claude declined the request (…). | The model refused the request. | Rephrase the request. |
| Empty response from the model. … | The request was declined or filtered, or the model returned nothing. | Rephrase it or send it again. |
| The response was cut off (max_tokens reached). | The model's answer became too long. | Ask for smaller steps, or start a New chat. |
| Empty response from server. / Received an empty reply. | The server returned no content. | Check the URL and whether the model is available. |
| The assistant needs an active connection. / No active session for this tab. | The session of the tab is closed. | Reconnect the tab. |
| The assistant is still responding. | A request is still running. | Wait, or click Stop. |
| Sending file contents to the AI is disabled in the settings. | Send file contents to the AI is off. | Turn it on under Settings → AI Pilot if AI Pilot may read files. |
| The file exceeds the … KB limit for AI requests. | In the editor's Edit mode, the file or selection is larger than Limit per file (KB). | Select a smaller part, or raise the limit under Settings → AI Pilot. |
AI Pilot stays unavailable although URL and model are saved? Without a token, kaiport only accepts model servers on localhost or 127.0.0.1. For a model server on another computer, enter its API key under API token, or any placeholder if the server doesn't check one.
See also Set up AI Pilot and Context and privacy.
kaiport Pro
| Message | What to do |
|---|---|
| AI Pilot is part of kaiport Pro. / Connecting through a jump host is part of kaiport Pro. | The feature needs kaiport Pro. Start the free trial or subscribe in the offer, or choose Restore purchases if you already subscribed. See Free and kaiport Pro. |
| The free version keeps up to 3 connections. kaiport Pro has no limit. | You have three saved connections. Delete one, or get kaiport Pro. |
| … more were not imported: the free version keeps up to 3 connections. | The import took as many connections as fit. |
| The port forwards of this connection did not start: port forwarding is part of kaiport Pro. | The session runs without its forwards. They start again with kaiport Pro. |
| On the Mac, kaiport Pro is available in the version from the Mac App Store. This download is the free version for now. | The download from kaiport.dev offers no purchase. Install kaiport from the Mac App Store to get kaiport Pro. |
| No App Store subscription found for this Apple ID. | Sign in to the App Store with the Apple ID you subscribed with, then choose Restore purchases again. |
| The App Store offer could not be loaded. Try again later. / The App Store could not be asked. | Check your internet connection and try again. Without a connection, an active kaiport Pro keeps working. |
| This Apple ID may not make purchases, for example because of Screen Time. | Allow purchases in Screen Time, or ask the organizer of your family. |
| The purchase waits for approval. | The purchase needs approval, for example with Ask to Buy. kaiport unlocks as soon as it goes through. |
| Active, but the renewal payment did not go through. | Check the payment method of your Apple ID. kaiport Pro keeps working while Apple retries the payment. |
To cancel kaiport Pro or ask for a refund, see Renewal and cancellation.
App issues
macOS asks for "kaiport Safe Storage"
kaiport keeps the key for your encrypted credentials in the macOS keychain, in the item "kaiport Safe Storage". With builds that are not signed, such as development builds, macOS asks for access to it. Enter your login password and click Always Allow, so macOS doesn't ask again. Without access, kaiport can't use the credentials it saved.
Linux: "Not available – secrets are only encoded"
Settings → About shows under Encryption how kaiport protects your credentials. On Linux it uses the Secret Service (libsecret), which GNOME Keyring or KWallet provide. If none is running, for example on some minimal desktops, the entry reads "Not available – secrets are only encoded": passwords, keys and tokens are then only encoded, not encrypted.
- Install a Secret Service provider, for example GNOME Keyring (package
gnome-keyring), and make sure it is unlocked when you log in. - Quit kaiport and start it again. Encryption now shows "System keychain (safeStorage)".
- Enter your saved passwords and your AI token again. Credentials you saved before stay only encoded until you save them anew.
Saved credentials are asked for again
kaiport can only decrypt credentials with the keychain of the computer and user account that stored them. If the keychain entry was removed or reset, or the data folder was copied from another computer, the saved passwords, passphrases and the AI token can no longer be read. kaiport then asks for passwords again when you connect.
Enter them once more and select Store encrypted for this connection; enter the AI token again under Settings → AI Pilot.
Tabs are not restored
With Settings → Terminal → Restore session (on by default), kaiport reopens the terminal windows that were open when you quit, and connects their tabs again.
- Only saved connections come back. Sessions opened with Quick connect are not restored.
- A split tab comes back with the connection of its focused pane.
- Windows you closed before quitting stay closed.
See Session restore.
Data folder and log file
| System | Data folder |
|---|---|
| macOS | ~/Library/Application Support/kaiport |
| Windows | %APPDATA%\kaiport |
| Linux | ~/.config/kaiport |
Settings → About shows the exact path under Data. On macOS, Help → Open Data Folder (settings, logs) opens it.
kaiport.log in this folder records unexpected errors with date and time. The file only exists once such an error has occurred. Include the relevant lines when you contact support. The AI audit log is ai-audit.jsonl; you can view it under Settings → AI Pilot → AI audit log. The other files are listed in Installation.
Updates
If you installed kaiport from the Microsoft Store or the Mac App Store, the store installs the updates; see Versions from the stores. These messages come from the version from kaiport.dev:
| Message | What to do |
|---|---|
| The update could not be installed: … | Click Download manually and install the new version over the old one. On macOS, only signed builds can install updates themselves. |
| The check failed: … | Check your internet connection and try Check for updates again later. |
| Updates are off in development builds. | Builds started from the source code don't update. Install kaiport from the download page. |
See Updates.