Skip to main content

SFTP extract connection errors: UnknownHostException

Introduction

SFTP extract connection errors can happen when the connector cannot resolve or reach the configured SFTP server. In Kleene, an UnknownHostException usually points to a hostname configuration issue rather than an authentication issue. A common cause is entering the host with the protocol prefix included, such as sftp://, when the connector expects only the hostname.

Issue description

An SFTP extract failed with the following error:

UnknownHostException: sftp://sftp.kleene.com

This means the SFTP client tried to resolve the full value sftp://sftp.kleene.com as if it were a hostname. Because sftp:// is a protocol prefix and not part of the DNS hostname, the host lookup failed before the connector could connect to the server.

Signs

You may be dealing with this issue if an SFTP extract fails before authentication and reports an UnknownHostException. The error may show the configured host value, and that value may include sftp:// at the start.

This is different from a credentials issue. If the hostname cannot be resolved, the connector has not reached the stage where it can validate the username, password, or key.

Basic troubleshooting steps

Start with the following checks to narrow down the cause of the error:

  • Review the full SFTP error message and confirm whether it contains UnknownHostException.
  • Check the configured SFTP host value in the connector.
  • Confirm whether the host includes the protocol prefix sftp://.
  • Remove the protocol prefix if it is present.
  • Use only the hostname, for example sftp.kleene.com.
  • Confirm the port is configured separately, usually 22 unless the customer uses a custom port.
  • Re-run the extract after updating the host configuration.

Common causes and how to fix them

Protocol prefix included in the hostname

The most likely cause is that the SFTP host was entered as sftp://sftp.kleene.com instead of sftp.kleene.com. Some tools accept full URLs, but SFTP connector host fields often expect only the DNS hostname.

How to fix it: update the SFTP host configuration to remove the protocol prefix. Use:

sftp.kleene.com

Do not use:

sftp://sftp.kleene.com

Hostname resolution failure

An UnknownHostException means the configured host could not be resolved by DNS. This can happen if the host is misspelled, contains unsupported characters, includes a protocol prefix, or points to a hostname that is not publicly resolvable from the extract environment.

How to fix it: verify the exact hostname with the customer or SFTP provider. If the hostname is correct, confirm whether it is reachable from the Kleene environment and whether any allowlisting or private networking is required.

Port entered as part of the hostname

Sometimes host and port are entered together in the host field, or the URL is pasted in full. If the connector expects the port separately, this can cause parsing or resolution issues.

How to fix it: enter the hostname and port in their separate fields. For example, set the host to sftp.kleene.com and the port to 22 or the customer-provided port.

Credentials investigated too early

Because the host cannot be resolved, the connector does not get far enough to test authentication. Changing usernames, passwords, or SSH keys will not fix an UnknownHostException caused by an invalid host value.

How to fix it: correct the hostname first. Only investigate credentials after the connector can resolve and reach the SFTP server.

Practical troubleshooting workflow

  1. Read the extract error and confirm it contains UnknownHostException.
  2. Copy the hostname shown in the error message.
  3. Check whether the value starts with sftp://.
  4. If it does, remove the protocol prefix from the connector host field.
  5. Confirm the host is set to sftp.kleene.com only.
  6. Confirm the port is configured separately.
  7. Save the connector configuration.
  8. Re-run the extract.
  9. If the error changes to an authentication or permission error, continue troubleshooting credentials or access.
  10. If the host still cannot be resolved, verify the hostname and network access with the SFTP provider.

Best practices to avoid SFTP UnknownHostException errors

  • Enter only the hostname in the SFTP host field.
  • Do not include sftp:// in the hostname.
  • Keep the port in the connector's port field rather than appending it to the host unless the connector explicitly supports that format.
  • Confirm the exact hostname with the customer or SFTP provider.
  • Treat UnknownHostException as a host or DNS issue before investigating credentials.
  • Document SFTP configuration examples for customers so they know which parts of the URL to enter.
  • Re-test the extract after each configuration change to confirm whether the failure has moved past host resolution.

Additional information

For this issue, the hostname was configured incorrectly with the protocol prefix included. The connector attempted to resolve sftp://sftp.kleene.com as a hostname, which caused the UnknownHostException.

The fix is to update the SFTP host configuration to use only:

sftp.kleene.com

Credentials are not the issue until the connector can successfully resolve and reach the SFTP server.

Related to

Powered by Zendesk