Polipo troubleshooting usually starts with one of a few familiar symptoms: the browser cannot connect, the proxy refuses to start, pages load but nothing is cached, or certain sites fail. Most of these have simple causes that you can confirm in minutes with the right checks.
Work through the sections in order. Each one names the symptom, the likely cause and the fix. Keep the proxy running in the foreground while testing so messages appear immediately in your terminal.
The Proxy Will Not Start
If the program exits right away, the most common reason is that the port is already in use. Another proxy instance, or a different service, may be listening on 8123. Check with ss -ltnp and either stop the other program or choose a different proxyPort.
ss -ltnp | grep 8123
polipo proxyPort=8124A second cause is a typo in the configuration file. An unknown variable name or a badly quoted value can stop startup. Run with -c pointing at the file and read the message it prints, then compare names against the list shown by polipo -v.
Browser Shows Connection Refused
A refused connection means nothing is listening where the client is looking, or the proxy rejected the client. Confirm the address and port in the browser match proxyAddress and proxyPort. If the browser is on another machine, the proxy must not be bound only to 127.0.0.1.
- Match the browser's proxy host and port to the configuration.
- Bind to a LAN or wildcard address for remote clients.
- Add the client's network to
allowedClients. - Check any firewall on the proxy machine for the chosen port.
Forbidden or access denied pages
If the proxy answers with an error page instead of refusing outright, it is running but rejecting the client or the URL. Review allowedClients, and if you use a forbiddenFile, check whether one of its patterns matches the site.
Permission Errors
Errors about writing files usually involve the cache directory, the log file or the PID file. The account running the proxy needs write access to each of these locations. Creating the directories and setting the owner normally resolves it.
sudo mkdir -p /var/cache/polipo
sudo chown proxyuser: /var/cache/polipoPorts below 1024 require extra privileges on most systems. Staying with the default 8123 or another high port avoids running the proxy as root, which is safer.
Nothing Seems to Be Cached
An empty cache is often expected rather than broken. HTTPS requests are tunnelled and never stored, and responses marked as private or uncacheable are skipped. Test with a plain HTTP resource that is known to be cacheable, then look in the cache directory.
| Possible cause | How to check | Fix |
|---|---|---|
| Disk cache disabled | Is diskCacheRoot empty? | Set a valid directory |
| Directory not writable | Check owner and permissions | Change owner to the proxy user |
| Traffic is HTTPS | Look at the URLs requested | Expected; HTTPS is tunnelled |
| Server forbids caching | Inspect response headers | Expected; respect the server |
HTTPS Sites Fail to Load
Secure sites travel through the proxy using the CONNECT method. If they fail while HTTP works, check the ports allowed for tunnelling. Variables such as tunnelAllowedPorts control which destination ports may be tunnelled, and port 443 must be included.
Some very modern sites or protocols may not work well through an archived proxy. If only a few sites fail, test them without the proxy to confirm whether the proxy is really the cause.
Slow Responses or DNS Failures
Delays before every request often point to name resolution. The proxy can use its own resolver settings, such as dnsNameServer, and it can be told whether to query IPv6 records. Misconfigured resolvers or broken IPv6 routes cause timeouts that look like general slowness.
- Test resolution on the proxy machine with
digorgetent hosts. - Set a reliable resolver with
dnsNameServerif needed. - Adjust IPv6 query behaviour if IPv6 is not routed on your network.
Parent Proxy Problems
When using parentProxy or socksParentProxy, every request depends on the upstream. If the upstream is down, all requests fail. Check that the parent is running and reachable from the proxy machine, and confirm the protocol type matches. The SOCKS guide has a full example.
Using Logs Effectively
Running in the foreground shows messages directly. For a service, set logFile to a writable path and read it after reproducing the problem. Note the exact time of a failure so you can match it to log lines quickly.
A Quick Diagnostic Checklist
When you are unsure where to start, run through a short sequence that isolates the problem. Each step either confirms that a layer works or points to the layer that needs attention.
- Is the process running, and is the port listening?
- Does
curl -xfrom the proxy machine itself succeed? - Does the same test work from the client machine?
- Does the failing site work without the proxy at all?
Write down the result of each step. If the proxy machine succeeds but the client fails, focus on addresses, client rules and firewalls; if both fail, focus on the proxy's own configuration, DNS or upstream connectivity. This simple split saves a lot of guesswork.
Polipo Troubleshooting FAQs
Another program is listening on the same port. Stop it or start the proxy on a different port with proxyPort.
The proxy may be bound to 127.0.0.1 or the clients may be missing from allowedClients. A firewall can also block the port.
Check that port 443 is allowed for tunnelling with tunnelAllowedPorts, and test the site without the proxy to compare.
Run the proxy in the foreground or set logFile to a writable location and read the log after reproducing the issue.
Conclusion
Polipo troubleshooting becomes routine once you know the patterns: busy ports and config typos stop startup, address and client rules cause refusals, permissions block caching, tunnel ports affect HTTPS and resolvers cause delays. Check each in turn and most issues resolve quickly.
If a problem persists, compare your setup against the configuration guide and remember that the project is no longer maintained, so some modern sites may never work perfectly through it.
