Troubleshooting · DockDuck Docs

What the host-key and certificate prompts mean, how to read DockDuck's remote error codes, and the current limitations — SSH-key and agent auth aren't supported yet, and FTPS is implicit-TLS only.

What this is. A guide to the prompts and error codes you might hit on a remote connection, and an honest list of what isn’t supported yet. DockDuck turns raw socket and protocol errors into a short message plus a stable code (like DD-NET-60) you can quote when asking for help.

Host key changed

The first time you connect to an SFTP server, DockDuck shows its host-key fingerprint and asks you to Trust & Connect. After that, it expects the same key every time.

If a trust prompt reappears for a server you’ve used before, the host key has changed. That happens legitimately when a server is rebuilt or its SSH keys are rotated — but it’s also exactly what a man-in-the-middle attack looks like.

You know why it changed (rebuild, key rotation): verify the new fingerprint against the server, then trust it.
You don’t know why: stop. Confirm with whoever runs the server before trusting the new key.

You’ll see DD-SSH-001 — “The server’s identity (host key) isn’t trusted yet.” — while the key is pending trust.

Add image — The host-key-changed warning prompt showing the new fingerprint and asking you to re-verify before trusting

public/docs/img/remote-troubleshooting-1.png

Warning

DockDuck remembers trusted host keys per host. Removing the saved server forgets its trusted key too (unless another saved server shares the same host), so a fresh connection will prompt again.

Certificate trust (FTPS / WebDAV-HTTPS)

The same idea applies to TLS certificates. An unknown certificate surfaces DD-TLS-001 — “The server’s certificate isn’t trusted yet.” — with its fingerprint. Verify it matches your server, then trust it to pin it for that host.

Timeouts and connection errors

Network failures map to clear messages with a DD-NET-… code carrying the underlying POSIX number:

You see	What it means	What to try
The server didn’t respond in time.	A timeout — the host is slow or unreachable.	Check the address, port, and that you’re on the right network or VPN.
The server refused the connection.	Nothing is listening on that port.	Confirm the port and that the service is running.
Can’t reach the server.	No route to the host.	Check the address and your network.
Authentication failed.	Wrong username or password.	Re-enter credentials in the Edit sheet.
The connection was lost.	The session dropped (`DD-NET-003`).	Reconnect from the sidebar and try again.

FTP servers report their own reply codes, surfaced as DD-FTP-… — for example DD-FTP-530 (“Login failed — check the username and password.”) or DD-FTP-550 (“file not found or no permission”).

Plain FTP is unencrypted

Plain FTP sends your username and password in the clear. DockDuck flags every FTP server with an orange Not encrypted badge in Settings → Servers as a standing reminder.

Warning

Prefer SFTP or FTPS whenever the server supports it. Use plain FTP only on a trusted local network, and never with credentials you reuse elsewhere.

Current limitations

We’d rather be upfront than surprise you:

SSH key and agent authentication aren’t supported yet. SFTP connects with a password only. Selecting SSH key or Agent raises DD-AUTH-001 — ”… authentication isn’t available yet — use Password.” Password auth is the supported path for now.
FTPS is implicit-TLS only. DockDuck negotiates TLS from the start of the connection. It does not support explicit FTPS (the AUTH TLS / StartTLS upgrade on a plain control channel). If your server only offers explicit FTPS, use SFTP instead.
No local + remote split view yet. There’s no single side-by-side pane that shows a local folder and a remote one at once. Open two tabs or windows and drag between them. See transfers.

Reading an error code

Every remote error is shown as a friendly message followed by a code in parentheses — for example “The server didn’t respond in time. (DD-NET-60)”. The prefix tells you the family:

DD-SSH-… — SSH host-key trust
DD-TLS-… — TLS certificate trust
DD-NET-… — network / socket
DD-FTP-… — an FTP server reply
DD-AUTH-… — an unsupported auth method
DD-MNT-… — a failed SMB/WebDAV mount
DD-CFG-… — a malformed server address

Quote the full code when you reach out — it pins down exactly what happened.

Where to go next

The Connect sheet — every field, and the trust prompts.
Managing servers — saving, editing, and defaults.
Transfers — copy, move, and recursive folder transfers.
Remote servers overview — the four protocols at a glance.