Troubleshooting¶
Work down this page in order. The first three checks resolve most cases.
1. Is the proxy running?¶
Open the console and look at Health. It reports the proxy service, the cache directory, disk and memory, and explains each deduction.
From a shell:
If Squid is not running:
sudo squid -k parse # syntax check - silent if the file is good
sudo tail -50 /var/log/squid/cache.log
sudo journalctl -u squid -n 50 --no-pager
A configuration error is the usual cause, and squid -k parse names the file
and line. If you have just applied a change from the console and the proxy did
not come up, it will already have rolled itself back — see
Applying Changes.
2. Can the proxy reach the internet?¶
If this fails, the problem is the instance's own connectivity — routing, NAT, firewall — and not the proxy. See AWS · Azure · Google Cloud.
3. Can the client reach the port?¶
From the client:
| Result | Meaning |
|---|---|
succeeded |
The network path is fine — the problem is above the network layer |
timed out |
Blocked by a security group, NSG or firewall rule |
refused |
Reached the host, but nothing is listening — back to step 1 |
In PowerShell, write curl.exe rather than curl
Every curl command on this page works on Windows, but PowerShell aliases
curl to Invoke-WebRequest, which does not understand -x and fails with
a parameter error rather than a proxy error. Diagnosing a proxy with the
wrong tool wastes a lot of time, because the failure looks like the thing
you are investigating.
Reading the result codes¶
Logs and Live Traffic show these in the console. The result code is the field that tells you what happened.
| Code | Meaning |
|---|---|
TCP_MISS/200 |
Fetched from the origin. Normal |
TCP_HIT/200 |
Served from cache. Normal |
TCP_TUNNEL/200 |
An HTTPS tunnel, logged when it closed. Normal |
TCP_DENIED/403 |
Blocked by an access rule |
TCP_DENIED/407 |
Authentication required, none supplied |
TCP_MISS/503 |
Could not reach the destination |
TCP_MISS/504 |
The destination timed out |
If a request does not appear at all, it never reached the proxy. Back to step 3.
Common problems¶
A client gets 403 Forbidden¶
Its address is not in the configured client networks. This is the most common single cause, and it is what you get when a subnet was added to the cloud firewall but not to the appliance.
Find the client address in the traffic log, then check it against Proxy Settings → client networks. An IPv6 client address here almost always means IPv6.
Every client gets 403, and the client networks look right¶
A different fault, and the giveaway is every. One client being refused is usually its address; the whole network being refused on an appliance that was working is not.
It affects appliances built before this was fixed, and only after you have applied a change from the console. The image ships with the client-network allow in place, so a newly launched appliance proxies correctly — it is the first apply, replacing that configuration, that removes it.
Check whether the generated configuration permits your networks:
1 means this is not your problem. 0 means the configuration defines your
client networks but never permits them, so every request falls through to the
default deny.
Restore access with the override file, which is never generated and never overwritten:
echo 'http_access allow localnet' | sudo tee -a /etc/squid/local.conf
sudo squid -k parse && sudo squid -k reconfigure
That survives later applies, which is what makes it a usable stopgap. Upgrade when a newer image is available: the fix is in the configuration generator.
Remove the override once you have upgraded
It is not harmless to leave behind. local.conf is included above the
generated access rules, so this line allows the whole client network before
any of them are considered — including the rule that requires users to sign
in. On an upgraded appliance with directory authentication switched on, an
override left in place lets every client through without credentials,
and nothing in the console shows it.
sudo sed -i '/^http_access allow localnet$/d' /etc/squid/local.conf
sudo squid -k parse && sudo squid -k reconfigure
Then confirm the generated configuration carries the allow itself:
Why this was not obvious sooner
The same appliances have a second fault that conceals the first: the post-apply health probe cannot work out the appliance's own address, so every apply fails verification and reverts. While that is happening the broken configuration never reaches a running proxy, and what people report is "my rule did not take effect" rather than a denial.
HTTPS does not work but HTTP does¶
Nearly always the client. Check that https_proxy is an http:// URL:
export https_proxy="http://10.0.1.20:3128" # correct
export https_proxy="https://10.0.1.20:3128" # wrong - will fail
The scheme describes how the client talks to the proxy, not what the proxy fetches. See HTTPS and CONNECT.
An access rule has no effect¶
Check in this order:
- Has it been applied? Rules do nothing until you apply them — see Applying Changes.
- Is an earlier rule matching first? Evaluation stops at the first match. Access Rules shows the order.
- Is the rule in
local.conf? Access rules do not work there. See Configuring Squid Directly. - Does the domain have a leading dot?
example.commatches only that exact name;.example.commatches subdomains too.
An apply is refused before anything changes¶
The Validate step runs Squid's own parser over the staged configuration, so a refusal here means the proxy is untouched and still serving the previous configuration. Nothing is broken and nothing needs restoring.
Read the message: where the fault comes from one of your rules it names that rule, so go to it, correct it, and apply again. Until it is corrected no other change can be applied either, because every apply stages the whole configuration — so fix it rather than working around it.
See Applying Changes for what each step does.
An HTTPS site cannot be blocked by path¶
Expected, and not fixable by configuration. The path is inside the encrypted session and never sent to the proxy. See HTTPS and CONNECT.
An authentication helper appears not to respond¶
Check the path. Older Squid packages used /usr/lib/squid3/, which appears in
many tutorials but does not exist on this image.
Running a program that is not there produces silence, which looks exactly like a backend timeout. See Authentication Backends.
Everyone is prompted to sign in, and nothing works¶
The rule requiring authentication is being evaluated after a deny. On a console-managed appliance, check the rule order in Access Rules.
An instance loses its cloud identity¶
Metadata requests are being sent through the proxy. Add the metadata address to
no_proxy on every client:
This breaks IAM roles on AWS, managed identities on Azure and service accounts on Google Cloud, usually some time after the change that caused it.
Traffic stopped appearing, and the log files are empty¶
Check whether the logs rotated recently:
If access.log is zero bytes while access.log.1 is large and both share a
timestamp, the files rotated but Squid did not reopen them — it is still writing
into the renamed file, which nothing reads. The console shows no traffic, and
the disk keeps filling behind a log that looks rotated.
That reattaches it immediately, and traffic reappears. On images built before
21 August 2026 this recurs at every rotation; a scheduled squid -k rotate is a
reasonable stopgap until the appliance is replaced.
NONE_NONE/000 entries from 127.0.0.1 in the access log¶
This is the appliance checking itself. The health check opens a connection to the proxy port to confirm something is listening, then closes it without sending a request, and Squid logs that like any other transaction.
Harmless, and expected at the health polling interval. Alongside it you will see
successful GET requests to squid-internal-mgr/info, which is the console
reading Cache Manager for the connection counts the access log cannot provide.
Both stay in the native access log deliberately — when diagnosing the proxy they are exactly what you want to see — and neither is counted as customer traffic in the console's own analytics.
WARNING: Ignoring 172.31.0.0/16 because it is already covered¶
Seen in cache.log on every start and reload, on AWS instances in a default
VPC. It is Squid noting that first boot added your VPC's range to the client
list when the shipped RFC1918 baseline already covered it.
Harmless: the range is permitted either way, and detection deliberately widens the list rather than replacing it, so that an unreachable metadata service degrades to a working proxy rather than one that denies everyone.
The disk is filling up¶
Health reports disk use and will warn before it becomes a problem.
Logs rotate daily with 14 days retained. If they are not rotating:
Traffic data retention is separate and configurable — see Administration.
The proxy is slow¶
Squid handles requests on a single thread, so a saturated core is a real limit and extra vCPUs will not help. File descriptor exhaustion is the other common ceiling; Health reports both.
Check DNS as well — slow resolution looks exactly like a slow proxy:
See High Availability for scaling out.
Useful commands¶
sudo squid -k parse # validate configuration
sudo squid -k reconfigure # apply without dropping connections
sudo squid -k rotate # rotate logs now
squid -v | head -1 # version and build options
sudo tail -f /var/log/squid/access.log
sudo tail -f /var/log/squid/cache.log # Squid's own diagnostics
Reading Cache Manager by hand¶
Cache Manager carries the runtime statistics — connection counts, hit ratios and service times — that the Dashboard and Health are built on.
squidclient is not on this image
It was removed in Squid 7. Tutorials that reach for squidclient mgr:info
predate that; use curl through the proxy instead.
curl -s -x 127.0.0.1:3128 \
"http://$(awk '$1=="visible_hostname"{print $2}' /etc/squid/squid.conf):3128/squid-internal-mgr/info"
The URL has to name the proxy's own visible_hostname and port. Squid treats a
/squid-internal-mgr/ path as a management request only when it is addressed to
this proxy. Ask for http://127.0.0.1/squid-internal-mgr/info instead and the
request is allowed, then forwarded as an ordinary request to 127.0.0.1:80,
where nothing is listening — so you get a Squid error page and it looks like a
broken cache manager.
Replace info with active_requests, counters or 5min for other reports.
What to send us¶
squid -v | head -1
sudo squid -k parse
systemctl status squid --no-pager
sudo tail -50 /var/log/squid/cache.log
Plus the client's IP address and what you expected to happen. That set answers most of the first round of questions. See Support.