DocumentationExperience Cloud KCS

UnknownHostException errors when accessing SAP document hosts in Adobe Experience Manager

Last update: October 5, 2026

In Adobe Experience Manager (AEM), java.net.UnknownHostException errors occur when the server cannot resolve the hostname of an SAP document host. The issue is often environment-specific, where one AEM environment works correctly while another does not. To resolve the issue, add the SAP host to host resolution.

Description description

Environment

Adobe Experience Manager (AEM)

Issue/Symptoms

  • Adobe Experience Manager (AEM) cannot resolve the hostname of the SAP document host when integrating with external systems.
  • The error java.net.UnknownHostException:  appears during requests to the SAP document host.
  • The required hostname is not present in the server host resolution configuration, such as the /etc/hosts file.
  • The issue can be environment-specific, where one AEM environment (for example, production) works correctly while another environment (such as staging or development) does not.
  • Document download operations fail because the SAP document host cannot be resolved.

Resolution resolution

Follow the steps below to resolve the issue:

  1. Identify the SAP document host that AEM is attempting to access, for example, <sap-document-host>.
  2. Check the host resolution configuration on the affected AEM server, such as the /etc/hosts file, and verify whether an entry exists for the SAP document host.
  3. If the entry is missing, add the SAP document host to the /etc/hosts file using the following format: <sap-host-ip> <sap-document-host>. Replace <sap-host-ip> with the correct IP address of the SAP document host and < sap-document-host> with the corresponding hostname.
  4. Save the changes to the/etc/hosts file.
  5. Restart any relevant services if your environment requires a restart for the changes to take effect.
  6. Validate hostname resolution from the AEM server by running ping <sap-document-host>, and verify that the hostname resolves successfully.
  7. Retry the document download operation in AEM and confirm that the issue is resolved.
recommendation-more-help
experience-cloud-kcs-help-kbarticles