Skip to main content
Version: 10.0

Connectivity troubleshooting

Use this guide when a client cannot reach a webPDF server reliably or when endpoint calls fail with symptoms such as unknown host names, connection timeouts, connection refusals, or unreachable SOAP or REST endpoints.

This topic is not limited to a specific client technology. The same checks apply whether the caller is a browser, script, reverse proxy, Java application, .NET application, SAP system, or another integration environment.

If you first need to locate the relevant installation, configuration, or log directories, start with Directory structure.

1. Verify that webPDF started successfully​

Before checking DNS or firewall rules, confirm that the local webPDF instance itself is running correctly.

Recommended checks:

If you need a collected baseline for Support, create Support information before and after reproducing the problem.

tip

If the server did not start cleanly, a remote connectivity test will often fail for secondary reasons. Always confirm the local server state first.

2. Test the server locally on the webPDF host​

Run the first functional checks directly on the machine where webPDF is installed.

Typical local test URLs and reference pages for the expected response format:

  • Portal: http://localhost:8080/webPDF/
    Compare with the Admin Portal entry points described under Login.
  • SOAP example endpoint: http://localhost:8080/webPDF/soap/converter?wsdl
    Compare with SOAP Web Services and SOAP Web Service API.
  • REST OpenAPI document: http://localhost:8080/webPDF/rest/openapi.json
    Compare with REST Web Services and OpenAPI.
  • Health endpoint: http://localhost:8080/webPDF/health/ready
    Compare with Health API.

If HTTPS is configured, adjust the protocol and port accordingly. For connector details, see Server configuration and Ports.

Interpretation:

  • First distinguish whether the endpoint is reachable at all or whether the returned content is also plausible for that endpoint.
  • If the URL cannot be opened at all, the problem is usually local startup, connector, port, or network related.
  • If the URL opens but the response does not match the documented endpoint behavior, the problem is more likely related to endpoint selection, API availability, service state, proxy rewriting, or another configuration detail.
  • If localhost does not work, the problem is local to the webPDF server or its configuration.
  • If localhost works but the configured host name does not, the problem is usually outside the webPDF application itself.
  • If only some endpoints fail or return unexpected content, compare the affected API with the status shown under Web Services and Health API.

3. Test the configured server address​

After localhost works, test the address that external clients are supposed to use.

Examples:

  • http://PORTAL_URL/webPDF/
  • http://PORTAL_URL/webPDF/soap/converter?wsdl
  • http://PORTAL_URL/webPDF/rest/openapi.json
  • http://PORTAL_URL/webPDF/health/ready

When testing, make sure that:

  • the host name is correct
  • the protocol matches the deployment (http or https)
  • the port is correct
  • the path still contains /webPDF with the correct casing

For the endpoint structure, see:

4. Check host name and DNS resolution​

If the error indicates an unknown host or name resolution problem, verify that the client can resolve the configured server address.

Typical checks from the calling environment:

  • resolve the configured host name
  • compare short host name versus fully qualified domain name (FQDN)
  • if needed, test temporarily with the server IP address to isolate DNS from general network connectivity

Typical findings:

  • localhost works, but <host> does not: DNS, host file, or client-side configuration issue
  • FQDN works, but short host name does not: DNS suffix or name resolution scope issue
  • IP address works, but host name does not: DNS issue rather than a webPDF issue
caution

Do not keep IP-address-based test URLs as the final configuration unless this is intentional for the environment. Prefer the intended DNS name once name resolution works reliably.

5. Check network path, port, and intermediaries​

If the host name resolves correctly, verify that the client can actually connect to the server and port.

Typical causes outside webPDF:

  • local firewall on the server
  • network firewall between client and server
  • reverse proxy or load balancer misconfiguration
  • missing routing between network segments
  • wrong connector port or disabled connector

Use the effective connector configuration as the reference. See:

If a proxy or gateway is used, test both paths separately when possible:

  • client -> proxy or gateway
  • proxy or gateway -> webPDF server

6. Compare API availability with health and administration status​

If the network path is open but requests still fail, compare the observed behavior with the internal server status.

Useful pages:

Examples:

  • /health/live is UP, but /health/ready is DOWN: the server process is running, but the API is not ready for requests
  • the Web services administration page shows an error icon: one or more services are not available even though the server itself is up
  • the connector is available, but a specific SOAP or REST endpoint still fails: check service-specific status and logs

7. Review logs and collect support data​

When the root cause is not obvious from endpoint tests alone, review the logs and collect support data in a structured way.

Recommended sequence:

  1. Reproduce the issue once.
  2. Review the log files.
  3. If more detail is required, use Debug mode temporarily.
  4. Reproduce the issue again.
  5. Download Support information.
  6. Return the log level to normal after the analysis.

For a broader support-oriented workflow around logs, startup behavior, connector configuration, and runtime settings, see Files troubleshooting.

8. Client-specific follow-up checks​

Once the server itself, the host name, and the network path are verified, continue with the client-specific integration setup.

Typical examples:

Quick interpretation matrix​

ObservationLikely area
localhost fails on the webPDF serverlocal webPDF startup or configuration
localhost works, host name failsDNS or host name resolution
host name resolves, but port is unreachablefirewall, routing, proxy, or connector
/health/live is UP, but /health/ready is DOWNserver started, but API not ready
portal works, but a specific SOAP or REST endpoint failsAPI-specific or service-specific issue