How to debug wget connections

HTTP and HTTPS transfers performed by wget underpin configuration management, package retrieval, and scripted backups on unattended Linux systems. Connection failures, hangs, or corrupt downloads in these flows can derail deployments and quietly damage archived data.

The wget client passes each request through DNS resolution, TCP connection setup, optional TLS negotiation, and HTTP or HTTPS exchanges, using options from the command line, environment variables, and configuration files such as /etc/wgetrc. The –debug flag expands the usual progress display into a trace of lookups, socket operations, TLS details, HTTP headers, proxy use, and retries, making it possible to pinpoint the exact phase where failures occur.

Verbose logging can expose full URLs, cookies, and authentication headers, so debug output requires careful handling and storage with restricted permissions. The procedure below assumes wget 1.21 or later on Ubuntu or a similar Linux distribution with a working resolver and certificate store; wording and library versions may differ slightly on other platforms. Debugging should focus on short, representative downloads rather than large production transfers to avoid unnecessary load while troubleshooting.

1. Capture a full connection trace from wget in a log file using the –debug flag.

   $ wget --debug https://www.example.com/data.tar.gz 2>&1 | tee wget-debug.log
   --2025-12-08 09:12:03--  https://www.example.com/data.tar.gz
   DEBUG output created by Wget 1.21.2 on linux-gnu.
   URI encoding = ‘utf-8’
   Resolving www.example.com (www.example.com)... 93.184.216.34
   Connecting to www.example.com (www.example.com)|93.184.216.34|:443... connected.
   HTTP request sent, awaiting response... 200 OK
   Length: 12345 (12K) [application/octet-stream]
   Saving to: ‘data.tar.gz’
   ##### snipped #####

   Using tee keeps output visible while preserving a complete trace in wget-debug.log for later inspection.

   Debug logs can reveal full URLs, tokens, and cookies, so logs should be stored with restricted permissions and redacted before sharing.

2. Search the debug log for hostname resolution and TCP handshake entries to confirm DNS and reachability.

   $ grep -E 'Resolving|Connecting to|failed' wget-debug.log
   Resolving www.example.com (www.example.com)... 93.184.216.34
   Connecting to www.example.com (www.example.com)|93.184.216.34|:443... connected.
   Connecting to www.example.com (www.example.com)|93.184.216.34|:443... failed: Connection timed out.
   ##### snipped #####

   Failures at the Resolving stage suggest issues with DNS servers or resolver configuration, whereas failures at Connecting to usually point to routing, firewall, or proxy problems.

3. Inspect proxy-related lines in the debug log to determine whether traffic is traversing an HTTP proxy.

   $ grep -i 'proxy\|CONNECT' wget-debug.log
   DEBUG: Using HTTP proxy http://proxy.example.net:3128
   CONNECT www.example.com:443 HTTP/1.1
   ##### snipped #####

   Unexpected proxy entries often originate from environment variables such as http_proxy or settings in /etc/wgetrc and can cause policies like HTTPS interception, authentication prompts, or blocked destinations.

4. Scan the log for TLS and certificate messages to detect failures during HTTPS negotiation.

   $ grep -i 'certificate\|tls\|ssl' wget-debug.log
   DEBUG CERTIFICATE: subject `/CN=www.example.com', issuer `/CN=Example-CA'
   ERROR: cannot verify www.example.com’s certificate, issued by `/CN=Example-CA':
     Unable to locally verify the issuer’s authority.
   ##### snipped #####

   Disabling certificate checks with options such as –no-check-certificate removes verification of the server identity and enables man-in-the-middle attacks, so it should only be used briefly on trusted networks for diagnostics.

5. Review HTTP request and response lines to understand redirects, authentication challenges, and final status codes.

   $ grep -E 'HTTP/' wget-debug.log
   ---request begin---
   GET /data.tar.gz HTTP/1.1
   Host: www.example.com
   ##### snipped #####
   HTTP/1.1 302 Found
   Location: https://downloads.example.com/data.tar.gz
   HTTP/1.1 401 Unauthorized
   ##### snipped #####

   Repeated 3xx redirects, loops between hosts, or persistent 401 Unauthorized responses usually indicate outdated URLs, missing custom headers, or incorrect credentials that must be adjusted with appropriate wget options.

6. Repeat the download with corrected URL, proxy, or authentication options to confirm that wget completes the transfer cleanly.

   $ wget --header='Authorization: Bearer TOKEN' https://downloads.example.com/data.tar.gz
   --2025-12-08 09:20:17--  https://downloads.example.com/data.tar.gz
   Resolving downloads.example.com (downloads.example.com)... 203.0.113.10
   Connecting to downloads.example.com (downloads.example.com)|203.0.113.10|:443... connected.
   HTTP request sent, awaiting response... 200 OK
   Length: 12345 (12K) [application/octet-stream]
   Saving to: ‘data.tar.gz’
   
   data.tar.gz        100%[===================>]  12.06K  --.-KB/s    in 0.1s
   
   2025-12-08 09:20:18 (120 KB/s) - ‘data.tar.gz’ saved [12345/12345]

   Successful troubleshooting is indicated by stable connection stages, a final 2xx status code, and a closing line showing the file saved with the expected size and path.