VPN not working or not connecting? Start here
· Updated 18 September 2026 · SparkBox team
The dashboard tile is red, the media pipeline says "VPN needs attention", and downloads have stopped. Before you change anything: that is the kill-switch doing its job, not a second problem. When the VPN tunnel is down, SparkBox deliberately cuts the download apps off from the network — nothing can leak. Your one real problem is the tunnel, and almost every tunnel problem is one of four causes. This guide walks you through reading the logs and matching what you see.
The 10-second version: read Gluetun's own logs first — docker logs sb-gluetun --tail 100 — then match what you see to a cause below. Tunnel never establishes? Provider credentials or server selection. Establishes but nothing works? DNS or a stale app container. Connects and disconnects every few seconds? The server pool is too narrow. Red tile but downloads work? You're looking at a badge that samples a flapping tunnel.
Quick vocabulary. Gluetun is the small container that runs your VPN client and forces the download apps to go out through its tunnel. WireGuard and OpenVPN are the two VPN protocols it can speak. A tunnel is the encrypted connection to your VPN provider's server. The kill-switch is the routing rule that blocks the download apps when the tunnel is down, so nothing can use your real connection instead.
Step 0 — read the logs, not the tile
The dashboard tile answers one question: "is a tunnel up right now?" A tunnel that flaps — up, down, up — can look healthy the moment the badge checks and red a second later. The container's own log tells you what is actually happening:
docker logs sb-gluetun --tail 100If you prefer the dashboard, the same log is reachable from the app's card. Either way, match what you see to one of the four causes below and apply only that fix. Guessing from the badge alone is how people spend an evening changing settings that were never the problem.
Cause 1 — the tunnel never establishes at all
The log ends with an authentication error, a provider error, or just keeps retrying a handshake that never completes. In this case the tunnel is not up even for a moment, and no amount of MTU or DNS tuning can help — those are for tunnels that connect but misbehave.
Check your provider credentials
If you changed your VPN provider's password, or the provider rotates WireGuard keys, the old credential stops working and Gluetun can only fail. In the dashboard, open the VPN settings, re-enter the credential, and let SparkBox recreate the container — a restart alone does not re-read changed environment variables.
Check your server selection
If you pinned a specific server or a short list of cities, one of them may be offline, and Gluetun keeps trying only those. Loosen the filter to country-only, which gives Gluetun a large healthy pool to choose from. This is the single most common fix for "worked yesterday, dead today."
Check for a corrupt server cache
If the log shows Unexpected end of JSON input or similar while fetching the server list, Gluetun's cached list is damaged. Delete the cached server list and restart — Gluetun re-downloads a fresh list on boot.
Cause 2 — the tunnel is up but nothing works through it
The handshake succeeds, the tile is green, but apps can't reach anything. There are three usual suspects:
- DNS is not resolving inside the tunnel. If lookups die while the tunnel is up, the encrypted-DNS setting is forced on with no way off. See the VPN DNS guide for the one-line fix.
- An app started while the VPN was down. The download apps connect to the VPN gateway when they start. If the tunnel was down at that moment, the app keeps failing until it is restarted — even after the tunnel comes back. Once the tile is green, restart the app that is failing.
- Port forwarding through the VPN. qBittorrent behind a VPN needs a forwarded port to seed well; if you set that up and it broke, see the apps-can't-reach-the-VPN guide.
Cause 3 — the tunnel connects and disconnects every few seconds
The log is full of reconnects. This is the sneakiest one, because the tile can look healthy in the good moments. The cause in almost every case is a server pool that is too narrow: Gluetun keeps cycling a few pinned servers, and each reset knocks every download app offline for a moment.
The fix: loosen the server filter to country-only (the opposite of pinning), then recreate the container. If you genuinely need a specific server, pin one known-good one and monitor its log — but country-only is the stable default for a reason.
Cause 4 — red tile, but downloads are actually working
You're seeing a badge that sampled the tunnel during a down moment. Check the log: if it is flapping, this is Cause 3 in disguise. If it is solidly connected and downloads work, the tile will settle to green on its own — if it keeps alternating while everything works, open the container's log and look for the reconnect pattern anyway. A flapping tunnel is not "working fine"; it just has good timing.
When to ask for help
You've read the log, tried the one matching fix, and it still won't connect — or the log shows something that matches none of these sections. Post in d/sparkbox and paste the last 20 lines of docker logs sb-gluetun --tail 20, with keys, emails and hostnames redacted (your VPN username, WireGuard key and public IP stay out of a public thread). The log is what lets someone see the actual failure instead of guessing.
Questions, or did this not match your box?
Every guide here came from a real problem someone hit. If yours behaves differently, say so — that is how these get corrected, and how the fix gets prioritised.
We answer there rather than in a comment box, because that is where the people who have already solved it are.