HTTP Connection Errors

HTTP components (http_client input, http processor, http_client output, and websocket) can fail to connect due to network issues. Here are the most common errors and how to fix them.

Unable to Resolve Host

unable to resolve host '<hostname>'

DNS lookup failed for the target hostname.

1. Verify the hostname is correct (check for typos)
2. Test DNS resolution:

   nslookup <hostname>
   # or
   dig <hostname>

3. Check if DNS is working for other hosts
4. Try using an IP address instead of hostname to isolate the DNS issue

Connection Refused

connection refused by server at <host>

The remote server isn't accepting connections on the specified port.

1. Verify the server is running
2. Check you're using the correct port
3. Verify firewall rules allow the connection
4. If connecting to localhost, ensure the service is bound to the correct interface (not just 127.0.0.1 if you need external access)

Request Timed Out

request to <host> timed out

The connection or response took too long.

1. Increase the timeout setting in your component config:

   http_client:
     url: "http://slow-server.example.com/api"
     timeout: 30s  # increase from default 5s

2. Check for network latency or server performance issues
3. Verify the server is responding at all using curl

TLS Certificate Validation Failed

TLS certificate validation failed for <host>

The server's SSL/TLS certificate is invalid, expired, or not trusted.

1. If using self-signed certificates, add them to root_cas_file:

   http_client:
     url: "https://internal.example.com/api"
     tls:
       root_cas_file: "/path/to/ca-cert.pem"

2. For testing only, you can skip verification (not recommended for production):

   http_client:
     url: "https://internal.example.com/api"
     tls:
       skip_cert_verify: true

3. Check if the certificate has expired or the hostname doesn't match

Connection Reset

connection to <host> was reset by the server

The server abruptly closed the connection.

1. Check server logs for errors
2. Verify the server isn't overloaded or crashing
3. Look for network equipment (firewalls, load balancers) that might be terminating connections

Connection Broken During Data Transfer

connection to <host> was broken during data transfer

The server closed the connection while data was still being sent. This typically happens when the request takes too long or exceeds size limits.

1. Check if the server has request size limits you're exceeding
2. Look for server-side timeouts closing connections early
3. Check for network issues (firewalls, proxies) terminating long-running connections
4. For large payloads, use chunked transfer encoding or smaller batches