Troubleshooting

Squid TCP_MISS/503: what it means and how to find the cause

Squid sends 503 when it cannot reach the server: a failed connect, a failed DNS lookup or a parent's 503. How to read the tag, the errno and the timers.

· 16 min read · How we verify this

Key points

  • TCP_MISS/503 means Squid tried to fetch the page from the network and could not, so it sent its own 503 Service Unavailable. The cause is in the error page name, which %err_code logs and the X-Squid-Error header carries: ERR_CONNECT_FAIL (no TCP connection) or ERR_DNS_FAIL (no address).
  • ERR_CONNECT_FAIL comes with an errno. 111 is refused (nothing listening), 110 is timed out (packets dropped), 113 and 101 are no route. Only the last address tried is named, so check every address the name resolves to.
  • TCP_TUNNEL/503 is the same failure for a CONNECT (an https:// URL). The tunnel was never opened. NONE_NONE/503 means Squid sent the 503 before it classed the request at all. Squid 4 and older print that as NONE/503.
  • Defaults: connect_timeout 1 minute per origin address, peer_connect_timeout 30 seconds per parent, forward_timeout 4 minutes in total, forward_max_tries 25. With silent addresses, the 4-minute limit ends the request long before 25 tries.
  • dns_v4_first was removed in Squid 5, not 6. Happy Eyeballs replaced it. In Squid 5 and 6, a parent that answers CONNECT with 503 is counted as a failed peer and can be marked DEAD. Squid 7 stopped doing that.

TCP_MISS/503 in Squid's access.log means Squid tried to get the page from the network and failed, so it answered with its own 503 Service Unavailable. The server never sent that 503. Squid did. There are two common causes. Either Squid could not open a TCP connection to any address of the server (ERR_CONNECT_FAIL), or it could not resolve the name at all (ERR_DNS_FAIL). The access log line does not say which. The response header X-Squid-Error does, and so does the %err_code log field once you add it. TCP_TUNNEL/503 is the same failure for an https:// URL, and NONE_NONE/503 is a 503 sent before Squid had classed the request.

Find your line in this table, then read the section it points to.

access.log showsX-Squid-Error / %err_codeWhat failedCheck first
TCP_MISS_ABORTED/503 ... HIER_DIRECT/<ip>, short %trERR_CONNECT_FAIL 111Connection refused: nothing listening on that address and portIs the service up, and on that port and address family?
TCP_MISS_TIMEDOUT/503, %tr near 60000 or a multipleERR_CONNECT_FAIL 110No reply to the connect: packets droppedFirewall or route between Squid and the server
TCP_MISS_ABORTED/503, short %trERR_CONNECT_FAIL 113 or 101No route to the host or networkRouting on the Squid host, often IPv6
TCP_MISS_ABORTED/503 ... HIER_DIRECT/<ip>ERR_CONNECT_FAIL 13 or 1A local rule refused the connect (SELinux, firewall)Policy on the Squid host
TCP_MISS_ABORTED/503 ... HIER_NONE/-ERR_DNS_FAIL 0The name did not resolveSquid's resolver, and the name itself
TCP_TUNNEL/503 CONNECT host:443Either of the aboveThe same failures, for a tunnel that never openedAs above
TCP_MISS/503 ... FIRSTUP_PARENT/<ip> (or another parent code)The parent's own headerA parent proxy answered 503The parent's log
NONE_NONE/503%err_code503 sent before the request was classed%err_code, then SslBump settings

The _ABORTED suffix on refused and DNS failures appears in Squid 6 and later. Squid 5 logs those as plain TCP_MISS/503. The errno numbers are Linux values.

What TCP_MISS/503 means#

Squid writes one line per request to access.log. The field TCP_MISS/503 has two halves. The part before the slash is the result code: how Squid handled the request. The part after it is the HTTP status Squid sent to the client.

MISS means the answer was not served from the cache, so Squid went to the network for it. The Squid wiki defines it as "The response object delivered was the network response object". On a 503 nothing was delivered from the network. The miss is about the path Squid took, not about success.

503 is Squid's choice of status for a forwarding failure. Squid's connection code builds the ERR_CONNECT_FAIL error with status 503. It picks 504 only when Squid was revalidating a cached response that must be revalidated (flags.needValidation). The comment above that code quotes the HTTP caching rule that asks for 504 there. The DNS code builds ERR_DNS_FAIL with 503 too. Nginx sends 502 for a refused connection, so the same fault gets a different number on each proxy. That mapping is in 502 vs 503 vs 504.

The hierarchy code later on the line, such as HIER_DIRECT/192.0.2.10, says where Squid went. HIER_DIRECT is the origin server. HIER_NONE/- means no server was contacted. A parent code such as FIRSTUP_PARENT means Squid sent the request to another proxy.

TCP_MISS, TCP_TUNNEL, NONE_NONE and the suffixes#

Squid builds the result code in LogTags.cc. It starts from a base tag and appends suffixes.

  • TCP_MISS is an ordinary request: GET http://... and other methods that Squid forwards itself.
  • TCP_TUNNEL is a CONNECT request, which is how a client asks a proxy for an https:// URL. The tag is set when Squid starts the tunnel code, before it connects anywhere. So TCP_TUNNEL/503 means the tunnel was never opened, whatever the wiki's definition ("A binary tunnel was established") suggests. The exchange itself is covered in HTTP CONNECT tunnelling.
  • NONE_NONE is the empty tag. Its internal name is TAG_NONE. When no tag was set, the code prints NONE for the first part, then the rest of TAG_NONE, which is _NONE. Squid 4's code printed only NONE, so the same case reads NONE/503 in older logs and older forum posts.

Two suffixes describe errors. LogTags.cc appends _TIMEDOUT and _ABORTED. The wiki spells the first one TIMEOUT, but the code prints _TIMEDOUT, so search for that. In FwdState.cc, Squid sets _TIMEDOUT when the final error's errno is ETIMEDOUT. On Squid 6 and later it sets _ABORTED for any other error, including a refused connection and a DNS failure. Squid 5 set only _TIMEDOUT. The wiki says the same: since Squid v6, ABORTED "also appears when Squid communication with an origin server or cache_peer is impossible".

These suffixes are added in the forwarding code for ordinary requests. The tunnel code does not add them. A failed CONNECT logs plain TCP_TUNNEL/503, as in the log line quoted in Squid's own commit message, TCP_TUNNEL/503 CONNECT nxdomain.test:443 FIRSTUP_PARENT.

Add %err_code and %err_detail to the log#

The stock squid log format has no error field. The logformat reference defines err_code as "The ID of an error response served by Squid" and err_detail as "Additional err_code-dependent error information". Add both, with the attempt count:

text
logformat squid_err %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt %err_code/%err_detail attempts=%request_attempts
access_log daemon:/var/log/squid/access.log logformat=squid_err

The first line copies the built-in squid format from the reference and adds the new fields at the end. Put the access_log line in place of your current one, then run squid -k reconfigure. A refused connect then ends in ERR_CONNECT_FAIL/WITH_SERVER attempts=2. WITH_SERVER is the detail Squid's forwarding code adds when nothing more specific is known. It means the failure was on the server side of Squid.

%request_attempts is in Squid 6 and later. Squid 5's reference does not list it, so drop that field there. %err_code and %err_detail are in Squid 4 and later.

Keep the log format change. It costs one field per line, and every 503 then names its own cause.

ERR_CONNECT_FAIL: Squid could not open a TCP connection#

This is the 503 behind most TCP_MISS/503 lines. Squid had at least one address for the server, and every connection attempt failed. The page the client sees comes from the ERR_CONNECT_FAIL template:

text
The following error was encountered while trying to retrieve the URL: http://intranet.example/
Connection to 192.0.2.10 failed.
The system returned: (111) Connection refused
The remote host or network may be down. Please try the request again.

%E in the template becomes "The system returned". Squid's error code fills it with the errno number and its text. The response also carries the header X-Squid-Error: ERR_CONNECT_FAIL 111, where 111 is the same errno. The errno is the most useful part of the page. The Linux connect(2) man page gives the meaning of each:

ErrnoTextWhat it tells you
111Connection refusedconnect() "found no one listening on the remote address". The host is up; the service or port is wrong.
110Connection timed outNo answer at all. A firewall dropping packets, or a host that is down. Squid's own timer reports this errno too.
113No route to hostRouting or an ICMP reject on the way
101Network is unreachableThe Squid host has no route for that family. Typical for IPv6.
13Permission deniedA local policy. The man page's own example is SELinux stopping "an HTTP proxy" connecting to a port not labelled for HTTP.
1Operation not permitted"a local firewall rule" on the Squid host

Two limits matter here. First, the page names only the last address Squid tried. Squid tries every address it got, and FwdState.cc keeps "the actual error from last forwarding attempt". If a name has four addresses, the page shows one of them. Second, a TLS failure after the connect is a different page (ERR_SECURE_CONNECT_FAIL), not this one.

To reproduce what Squid saw, connect from the Squid host itself, to each address, on the same port. A test from your laptop does not cross the same firewall. For an https:// URL, the client side of the same 503 is covered in ERR_TUNNEL_CONNECTION_FAILED: what the proxy answered. Chrome hides the 503 page there, so curl or the access log is the only way to read it.

ERR_DNS_FAIL: no address to connect to#

If the name does not resolve, Squid never tries to connect. The log shows HIER_NONE/-, because no server was contacted. The page reads "Unable to determine IP address from host name", followed by "The DNS server returned:" and the resolver's message. Squid's DNS code supplies messages such as "Name Error: The domain name does not exist." and "Server Failure: The name server was unable to process this query." The header is X-Squid-Error: ERR_DNS_FAIL 0. The 0 is there because no system call failed.

Squid builds this error only for direct requests (HIER_DIRECT in peer_select.cc). Squid has its own DNS client. It takes name servers from /etc/resolv.conf unless dns_nameservers lists others, and reads /etc/hosts through hosts_file. Test against those same name servers, not whatever your shell happens to use.

Worked case: three silent addresses and a two-minute 503#

Here is one request walked through Squid's defaults. No test was run; the timings come from the configuration reference and the connection code.

Take a Squid 6 or 7 host with working IPv6. A client asks for http://intranet.example/. The name has one IPv6 address, 2001:db8::10, and two IPv4 addresses, 192.0.2.10 and 192.0.2.11. Suppose a firewall between Squid and the server drops every packet. It sends no reject, so each connect simply waits.

  1. Squid asks for A and AAAA records at once. Suppose the AAAA answer comes first. IPv6 then becomes the primary family and IPv4 the spare. The happy_eyeballs_connect_timeout text defines these terms that way.
  2. At 0 s, Squid opens the primary connect to [2001:db8::10]:80.
  3. At 0.25 s, the primary has not finished. happy_eyeballs_connect_timeout (250 ms by default) has passed, so Squid opens a spare connect to 192.0.2.10:80.
  4. At 60 s, the primary hits connect_timeout (1 minute) and fails with errno 110. There is no other IPv6 address.
  5. At about 60.25 s, the spare to 192.0.2.10 times out too. Squid keeps one primary and one spare attempt open at a time. So only now does it start 192.0.2.11.
  6. At about 120.25 s, that connect times out. No addresses are left.

The log line would then read TCP_MISS_TIMEDOUT/503 with %tr near 120250 and HIER_DIRECT/192.0.2.11. The fields added above would read ERR_CONNECT_FAIL/WITH_SERVER attempts=3. The client waits two minutes, then gets a page that blames only 192.0.2.11, with "(110) Connection timed out".

Change one thing: let the server send a TCP reset instead of dropping packets. Every connect then fails at once with errno 111. The same request ends in milliseconds as TCP_MISS_ABORTED/503. So %tr alone sorts the cause. Near a multiple of 60000 means packets dropped somewhere. A few milliseconds means something answered and refused.

The timers: connect_timeout, forward_timeout and forward_max_tries#

Four settings decide how long a 503 takes and how many addresses Squid tries. The defaults below come from cf.data.pre and are the same on the v4, v5, v6, v7 and master branches.

DirectiveDefaultWhat it limits
connect_timeout1 minuteOne TCP connect to an origin server
peer_connect_timeout30 secondsOne TCP connect to a cache_peer, unless its connect-timeout= option is set
forward_timeout4 minutesAll forwarding attempts for one request together
forward_max_tries25The number of forwarding attempts

The connect_timeout reference says it covers "the requested server or peer". Squid's code (Comm::Connection::connectTimeout) uses the peer's own timeout for a peer instead. So a parent gets 30 seconds, not 60. Each connect also gets no more than the time forward_timeout has left.

forward_max_tries does not count everything. The reference excludes "connection reopening attempts (enabled using connect_retries)" and "unfinished Happy Eyeballs connection attempts". A spare that is still connecting when another attempt wins is never counted. A spare that fails is.

Put the two limits together. In one address family, connects run one after another. With silent addresses, four 60-second connects use up the 4-minute forward_timeout. Squid stops there, far short of 25 tries. Raising forward_max_tries will not help in that case. Lowering connect_timeout will make the 503 arrive sooner. The same budget logic for other proxies is in timeout budgets.

About the v8 pages. squid-cache.org marks connect_timeout and forward_max_tries "not available in the v8 version of Squid". The directives are in cf.data.pre on the master branch, which is the v8 code, with the same defaults. The website's v8 set appears to be missing pages. Do not read the label as a removal.

IPv6: dns_v4_first was removed in Squid 5, not 6#

Many guides tell you to set dns_v4_first on when IPv6 causes 503s. That directive is gone. The Squid 5 release notes list it as "Removed. The new 'Happy Eyeballs' algorithm uses received IP addresses as soon as they are needed." It is not a Squid 6 change, as some answers claim. On Squid 5 and later the line produces ERROR: Directive 'dns_v4_first' is obsolete. and the note "Remove this line. Squid no longer supports preferential treatment of DNS A records." It does nothing else.

The release notes explain what replaced it. Address order is "now primarily controlled by DNS response time". If the AAAA answer comes first, Squid tries IPv6 first. "For previously cached IPs, Squid tries IPv6 addresses first." Three directives tune the race:

  • happy_eyeballs_connect_timeout, default 250 ms: the wait before the first spare connect.
  • happy_eyeballs_connect_gap, default none: a minimum gap between spare connects, across the whole Squid instance.
  • happy_eyeballs_connect_limit, default none: a cap on open spare connects. Setting it to 0 makes Squid try spares "only after all primary attempts fail".

What this means for a host that serves IPv4 only but publishes an AAAA record:

  • IPv6 refused or unroutable (errno 111, 113 or 101). The IPv6 attempt fails at once and Squid moves to IPv4. You get a 200, perhaps a little later.
  • IPv6 dropped silently. The IPv6 attempt hangs for up to 60 seconds. The IPv4 spare still starts after 250 ms, so the page usually loads. With happy_eyeballs_connect_limit 0, the spare waits for the full IPv6 timeout first.
  • Both families fail. You get ERR_CONNECT_FAIL, and the page shows the errno of the last attempt, which can be the IPv6 one.

To keep Squid off IPv6, the release notes name "firewall rules prohibiting IPv6 TCP connections" as the preferred method, with "DNS recursive-resolver configuration also available". Also, "These Happy Eyeballs changes do not affect peer selection." Squid still finishes one destination's addresses before it moves to the next parent. The same localhost-and-IPv6 trap on nginx is in why nginx tries ::1 when proxy_pass says localhost.

A parent proxy that answers 503#

If Squid forwards to a parent, a cache_peer line of type parent, the 503 may be the parent's. The hierarchy code then names a parent, such as FIRSTUP_PARENT/10.0.0.5. For a GET, Squid passes the parent's response to the client. The page and its X-Squid-Error header describe the parent's failure, so read the parent's log.

For CONNECT there is a version trap. A November 2023 thread on squid-users reported Squid 6.5 logging ERROR: Connection to 127.0.0.1:8123 failed about every 10 seconds. Squid could reach that parent. The parent was answering CONNECT with 503 because names failed to resolve on its side. Squid developer Alex Rousskov replied that "Squid v6 treats most CONNECT-to-peer errors as a sign of a broken peer", that 4xx answers were excluded in 2022, and that frequent failures get the peer "marked as DEAD". The reporter's log showed Detected DEAD Parent: 127.0.0.1:8123.

The source shows how that happens and when it stopped:

  • Squid 5. The CONNECT code counted every failed CONNECT through a parent against that parent, 4xx included. The commit that later reversed this says the change was "probably accidental".
  • Squid 6. Same, except 4xx answers. A parent's 503 counts as a failure. Each one logs ERROR: Connection to <peer> failed. After connect-fail-limit failures in a row (10 by default), Squid logs Detected DEAD Parent and stops using it. A successful connection resets the count.
  • Squid 7 and later. Commit 2e7dea3 (#1772), "Do not blame cache_peer for CONNECT errors", is on the v7 branch. Its message quotes the exact pair of lines above. The v7 code now says "we do not blame cache_peer for CONNECT failures (on top of a successfully established connection to that cache_peer)".

So on Squid 6, a parent that keeps getting CONNECT requests for names it cannot resolve can be marked DEAD while it works fine. The reporter put the cost plainly: "Especially in the case where you have a single cache_peer and cannot go direct. No benefit to marking it as dead." Upgrading to Squid 7 is the fix the developers made. A real connect failure to the parent still counts on every version.

NONE_NONE/503: a 503 before the request was classed#

NONE_NONE means the tag was never set. The wiki's description of NONE fits: "usually when the transaction fails before being classified". Add %err_code to see which error it was.

One path that leaves the tag unset is SslBump. In client_side_request.cc, a CONNECT that ssl_bump will handle goes to sslBumpStart() instead of tunnelStart(). So it never gets TCP_TUNNEL. Later, at step 3, Squid opens the server connection through the forwarding code (client_side.cc). If that connection fails, the 503 is logged against a request that was never classed. A related case, a TLS handshake sent to a plain-HTTP port, logs NONE_NONE/400 error:invalid-request, as shown in Should HTTPS_PROXY start with http:// or https://?.

Where this answer stops applying#

This page reads the Squid source on the v5, v6, v7 and master branches as of 18 November 2026. Nothing here was run against a live Squid, so the worked case shows what the code and defaults predict, not a measured trace. Distribution packages can patch Squid, so check squid -v and your own squid.conf. Errno numbers and texts are Linux values. Other systems number them differently. 503s from ICAP or eCAP services, ERR_SHUTTING_DOWN during a restart, and TLS failures after the connect are not covered. Neither are 403 refusals, which are access rules. Those are in why Squid logs TCP_DENIED/403 for every request. Finally, a 503 that the origin server itself sends is logged as TCP_MISS/503 too, with HIER_DIRECT. Its %err_code is -, and the page is the server's, not Squid's.

Frequently asked questions#

What does TCP_MISS/503 mean in the Squid access log?#

It means Squid went to the network for the request and failed, so it sent its own 503 Service Unavailable. Usually it could not open a TCP connection to the server (ERR_CONNECT_FAIL) or could not resolve the name (ERR_DNS_FAIL). The X-Squid-Error header or the %err_code log field says which.

What does "The system returned: (111) Connection refused" mean in Squid?#

The server's host answered, but nothing was listening on that address and port. Check that the service is running and listening on the right port and address family. The page names only the last address Squid tried, so test every address the name resolves to, from the Squid host itself.

What is the difference between TCP_TUNNEL/503 and TCP_MISS/503?#

TCP_TUNNEL/503 is a CONNECT request, which is how an https:// URL goes through a proxy, and the tunnel was never opened. TCP_MISS/503 is an ordinary request such as GET http://. The causes are the same. A browser hides the 503 page for CONNECT and shows ERR_TUNNEL_CONNECTION_FAILED instead.

What does NONE_NONE/503 mean?#

Squid sent the 503 before it classed the request as a miss or a tunnel, so the tag stayed empty. Squid 4 and older print the same thing as NONE/503. Add %err_code to the log format to see the error, and check ssl_bump rules, since bumped CONNECT requests are never tagged TCP_TUNNEL.

Can I still use dns_v4_first in Squid 6?#

No. It was removed in Squid 5, and Squid 5, 6 and 7 log it as an obsolete directive and ignore it. Happy Eyeballs replaced it. To stop Squid using IPv6, the release notes recommend firewall rules that block IPv6 TCP connections, or resolver configuration.

Why does Squid say "ERROR: Connection to <peer> failed" when the parent is up?#

On Squid 5 and 6, a parent that answers CONNECT with an error (except 4xx) is counted as a failed connection. After 10 in a row by default, Squid marks it DEAD. A parent returning 503 for names it cannot resolve triggers this. Squid 7 stopped counting CONNECT errors against the parent.

Primary sources#

Every normative claim on this page is checked against the specification or the vendor documentation listed here. Where behaviour is version dependent, the version is named in the text.

  1. Squid source, src/LogTags.cc (result code strings, NONE, _TIMEDOUT and _ABORTED)
  2. Squid error page template ERR_CONNECT_FAIL
  3. Squid error page template ERR_DNS_FAIL
  4. Squid source, src/HappyConnOpener.cc (ERR_CONNECT_FAIL with 503, errno kept, attempt limits)
  5. Squid source, src/FwdState.cc (final error, log tag suffixes, WITH_SERVER detail)
  6. Squid configuration directive logformat (err_code, err_detail, request_attempts)
  7. Squid configuration directive connect_timeout
  8. Squid configuration directive forward_max_tries
  9. Squid source, src/cf.data.pre on the v7 branch (defaults for all timers named here)
  10. Squid 5 release notes (Happy Eyeballs update, dns_v4_first removed)
  11. Squid configuration directive dns_v4_first
  12. squid-users, "6.x gives frequent connection to peer failed - spurious?" (November 2023)
  13. Squid commit 2e7dea3, Do not blame cache_peer for CONNECT errors (#1772)
  14. Squid wiki, SquidFaq/SquidLogs (result codes and hierarchy codes)
  15. Linux man page connect(2) (ECONNREFUSED, ETIMEDOUT, EACCES, EPERM)

Found something wrong, or behaviour that differs on your version? Report it with the version number and a primary source. Anything substantive is fixed in the page and logged on the corrections page. See editorial standards for how pages are researched, sourced and reviewed.

More in troubleshooting proxies#