Troubleshooting Connection Refused and Host Resolution Errors in Karate DSL

The Connectivity Gap

When running Karate DSL tests, the most common blockers are not logic errors in the feature files, but infrastructure failures where the framework cannot reach the target API. These typically manifest as java.net.ConnectException: Connection refused or java.net.UnknownHostException: Unable to resolve host. The goal is to determine if the failure exists in the Karate configuration, the JVM network layer, or the target environment itself.

Diagnostic Matrix

Step-by-Step Connectivity Validation

Follow these checks in order to isolate the failure point. Do not move to the next step until the current one is verified.

1. Validate the Resolved URL

Karate often uses karate-config.js to dynamically set the base URL based on an environment variable (e.g., karate.env). A typo here is the most frequent cause of UnknownHostException.

• Check: Open your karate-config.js and verify the logic assigning the URL.
• Verification: Run the test with the -Dkarate.env=dev (or your specific env) flag. Inspect the console output for the actual URL being called.

2. Isolate the Framework (The Curl Test)

Determine if the issue is specific to the Java Virtual Machine (JVM) or a general network failure. Run a request from the same machine and user account executing the tests.

# Run this from the terminal/command prompt
curl -v http://your-api-endpoint:port/health

• Success: If curl works but Karate fails, the issue is likely JVM proxy settings or SSL configuration.
• Failure: If curl also fails with "Connection refused," the target server is either offline or a firewall is blocking the port.

3. Inspect JVM Proxy Overrides

In corporate environments, the JVM may attempt to route all traffic through a proxy, even for internal localhost or .internal addresses. This often results in timeouts or 403 errors.

Check if http.nonProxyHosts is configured in your execution environment. If you are running via Maven or Gradle, ensure the following properties are passed to the JVM:

-Dhttp.nonProxyHosts="localhost|127.0.0.1|*.internal.company.com"

4. Handle SSL and Certificate Issues

If the target uses a self-signed certificate, the JVM will terminate the connection during the handshake, which can sometimes be misreported as a connection reset.

In your karate-config.js, you can disable certificate validation for non-production environments:

karate.configure('sslIgnoreCertErrors', true);

Risk: Never enable this for production environments, as it exposes the test suite to man-in-the-middle attacks.

Fixes Based on Findings

• If DNS failed: Correct the hostname in karate-config.js. Avoid hardcoding URLs in .feature files to ensure environment portability.
• If Port blocked: Verify the target service is listening on the expected port using netstat -an | grep <port> on the server.
• If Proxy interfered: Update the nonProxyHosts JVM argument to bypass the proxy for the target domain.

Escalation Criteria

If the following conditions are met, the issue is an infrastructure failure and should be escalated to the Network or DevOps team:

• curl fails with "Connection refused" from multiple machines in the same subnet.
• The target server logs show no incoming request attempts during the test execution window.
• DNS resolution works via nslookup, but the connection is dropped immediately after the TCP handshake.

Verification of Fix: Once the change is applied, execute a single scenario using the @smoke tag to verify the connection is restored before running the full suite.