Introduction
Modern software applications are built on distributed systems, where computers communicate across complex networks. While this web of interconnected hardware can seem intimidating, its behavior is governed by a set of logical, foundational concepts. This guide provides a clear framework for diagnosing and resolving common network connectivity issues.
The Journey of a Network Request
When a client (like your browser, the Docker client, or a CI/CD server) tries to communicate with your Artifactory server, its request travels through several stages. A problem at any of these stages can cause an error.
- DNS Lookup: The first step is translating the human-readable Artifactory URL (e.g., artifactory.mycompany.com) into a machine-readable IP address (e.g., 10.0.5.20). This is done by querying a Domain Name System (DNS) server.
- Forward Proxy: In many corporate environments, the outbound request is first sent to a forward proxy. This proxy manages and secures outbound traffic, forwarding the request toward the internet or internal network.
- Routers and Gateways: The request then travels across the network, hopping between various routers, firewalls, and gateways until it reaches the network where Artifactory is hosted.
- Reverse Proxy & Artifactory Host: Finally, the request arrives at the destination. It's typically handled first by a reverse proxy (like Nginx or Apache), which then forwards it to the Artifactory application itself. If you're using HTTPS, this is also where the TLS (SSL) connection is terminated.
Troubleshooting Common Network Errors
Here are common errors and how to troubleshoot them, broken down by where they might occur in the request's journey.
DNS Lookup Failures
If the very first step of resolving the Artifactory URL fails, your client will never know where to send the request.
- Common Errors: "Unknown Host", "No Route to Host".
- How to Test: Use a command-line tool like nslookup or dig from the client machine to check if the DNS name is resolvable.
nslookup artifactory.mycompany.com
A successful lookup will return the correct IP address. If it fails, you have a DNS configuration issue.
Try running the same command from the Artifactory server itself; if it works there but not on the client, the problem is with the client's DNS settings or a misconfigured private DNS.
Proxy Failures
A misconfigured forward proxy can block or mishandle requests on their way out from the client.
- Common Errors: Strange 401 Unauthorized or 403 Forbidden errors, or requests that "hang" and eventually time out. This can happen if the proxy is incorrectly configured or has security policies that block the request.
- How to Test: You can use curl to explicitly test the connection through the proxy.
# Test a request THROUGH the proxy
curl --proxy http://your-proxy-server:8088 https://artifactory.mycompany.com -v
Sometimes, a proxy should not be used for internal destinations. You can tell your client to bypass the proxy for your Artifactory URL using the NO_PROXY environment variable.
export NO_PROXY="artifactory.mycompany.com, 127.0.0.1"
Router and Gateway Failures
Problems in the intermediate network path can be tricky to diagnose as they are often intermittent.
- Common Errors: Intermittent "Connection reset by peer" errors. This suggests a device like a firewall or router between the client and server is dropping data packets.
- How to Test: Use traceroute (or tracert on Windows) to map the network path your request takes.
traceroute artifactory.mycompany.com
Look for lines with * * * or a sudden, persistent jump in latency (time). This indicates a problematic hop in the network path, and you may need to involve your network administrator to investigate that specific device.
Remote Host (Reverse Proxy & TLS) Failures
Even if a request reaches the Artifactory host, things can still go wrong at the reverse proxy or within the application itself.
Common Errors:
- "Connection reset by peer"
- 504 Gateway Timeout
- TLS/SSL certificate errors.
How to Troubleshoot:
Timeouts:
An error like 504 Gateway Timeout or "Connection reset by peer" often means the reverse proxy forwarded the request to Artifactory, but the application took too long to respond.
The proxy eventually gave up and closed the connection. This points to a performance issue within Artifactory that needs to be investigated.
TLS Handshake Issues:
For a https:// connection to work, the client and server must perform a "TLS handshake".
Is it a firewall or a TLS problem? A key test is to run curl -v https://artifactory.mycompany.com. If the command just hangs without printing lines like "ClientHello" or "ServerHello", it's likely a firewall is dropping the packets before the TLS handshake can even start.
True TLS errors: If the handshake starts but fails, curl will give a specific error message. Common causes include an expired or untrusted server certificate, or a mismatch between the URL you are using and the CN / SAN of the certificate.
Common Connection Errors Explained
It helps to know what different connection errors mean:
Connection Timeout: The client sent a request but received no response at all. The server might be offline, a firewall might be silently dropping the connection, or the IP/port could be wrong.
Connection Refused: The client reached the server, but the server actively rejected the connection. This usually means no service is listening on that port, the application has crashed, or a firewall explicitly blocked the request.
Connection Reset: A connection was successfully established, but it was abruptly terminated by the server or an intermediate device (like a load balancer or firewall) before the communication was finished.