When apt-get update stalls with waiting for headers, the client cannot successfully reach repository endpoints to retrieve package lists. This typically indicates a network, DNS, or repository configuration issue rather than a problem with the update process itself. This guide explains the causes, offers step-by-step diagnostics, and provides practical fixes so your package metadata refreshes reliably. By verifying sources, testing reachability, and aligning client and server settings, you can resolve most hangs and restore stable updates on Debian-based systems.
Common causes of apt-get update waiting for headers
The command hangs at waiting for headers when an HTTP or HTTPS request to a repository times out before the server sends response headers. Key contributors include DNS resolution failures, unreachable or misconfigured repository URLs, firewall rules that drop or rate-limit traffic, proxy misalignment, IPv4/IPv6 mismatches, and repository server outages or redirects.
Network, DNS, and routing
If DNS cannot resolve the repository hostname, or if packets cannot reach the IP, the handshake never completes and headers never arrive. Partial connectivity, asymmetric routing, or intermediate drops can also cause the connection to stall at the TCP stage.
Repository configuration issues
Incorrect URIs, missing distribution components, or deprecated mirrors lead to 404s or timeouts. Redirects from HTTP to HTTPS must be supported by the client and correctly configured to avoid hangs.
Step-by-step diagnostics
Work through these checks systematically to isolate the root cause. Each step narrows the problem domain between the client and the repository.
Verify /etc/apt/sources.list and sources list files
Ensure URIs use the correct protocol, hostname, path, and distribution codename. Comments and typos can break resolution silently.
Basic connectivity tests
Confirm that the host is reachable and that required ports are open. Start with name resolution, then TCP connectivity to the repository on port 80/443.
| Check | Command | What it verifies |
|---|---|---|
| DNS resolution | host <repo-host> or dig +short <repo-host> |
Hostname to IP mapping |
| HTTP connectivity | curl -Iv http://<repo-host>/ |
Reachability and redirects over HTTP |
| HTTPS connectivity | curl -Iv https://<repo-host>/ |
Reachability, TLS handshake, and redirects over HTTPS |
| Port 80/443 access | nc -zv <repo-host> 80 and nc -zv <repo-host> 443 |
TCP connectivity to package ports |
Compare HTTP vs HTTPS protocols
Switching between HTTP and HTTPS can bypass TLS-related stalls or certificate verification delays. Test each independently to identify which layer causes the hang.
IPv4/IPv6 and protocol preferences
Systems preferring IPv6 may attempt IPv4 fallbacks when IPv6 paths are misconfigured, creating stalls. Forcing APT to use IPv4 temporarily can confirm whether IPv6 is the contributor.
Practical fixes
Apply targeted adjustments based on the diagnostic outcome. Small changes to configuration, routing, or firewall policy often resolve the stalls without broader system changes.
Resolve DNS issues
Use reliable resolvers, check /etc/resolv.conf for conflicts, and confirm split-horizon DNS does not hide internal repository names. Testing with 8.8.8.8 or 1.1.1.1 can indicate whether the local resolver is the bottleneck.
Correct APT repositories and mirrors
Validate URIs, ensure the distribution name matches the repository layout, and confirm that redirects are followed as expected. Use the official repository mirror closest to your network path to reduce latency and misrouting.
Firewall and rate limiting
Inspect outbound and intermediate firewalls for packet drops, rate limits, or stateful inspection rules that interrupt idle handshakes. Ensure sustained connections to port 80/443 are permitted by security policies.
Proxy configuration
Set Acquire::http::Proxy correctly for APT, authenticate when required, and confirm the proxy does not terminate or delay TLS handshakes. Inconsistent proxy settings between shell and APT are a common source of hangs.
Tune APT timeouts and behaviour
Increase Acquire::Timeout and related retry parameters to allow longer initial waits when latency is expected. Combine with fixes to avoid masking underlying issues while providing more resilience under load.
When to escalate
If local fixes do not resolve the symptom, contact your network or hosting team to inspect ACLs, egress filtering, and routing. Repository maintainers may need to review mirror health if timeouts affect multiple clients from different networks.
Summary checklist
- Verify DNS resolution for repository hostnames
- Check that repository URIs are correct and up to date
- Test HTTP and HTTPS reachability with curl
- Confirm TCP connectivity to ports 80 and 443
- Align proxy settings between shell and APT
- Review firewall and rate-limiting policies
- Temporarily adjust timeouts and retries for diagnosis
- Consider IPv6 interactions if relevant
Related topics
These subjects often coincide with or follow resolution of waiting for headers: APT pinning, repository mirroring strategies, HTTPS certificate verification, and system time synchronization.
Conclusion
apt-get update waiting for headers is a connectivity symptom with clear network and configuration fingerprints. Methodical checks of DNS, protocol choice, proxies, firewall rules, and repository settings typically reveal the cause. Apply fixes iteratively, tune timeouts cautiously, and escalate to network or repository operators when local actions do not restore successful updates.