VPN connects but nothing resolves: the missing VPN_DOT switch

Published 27 July 2026 · Updated 31 July 2026 · SparkBox team

The VPN tunnel comes up, handshakes succeed, but the moment you try to load a site or reach a service, nothing resolves — no error, just dead lookups. The cause isn't your firewall or your keys. It's a setting called VPN_DOT that controls encrypted DNS, and it was never written to your config file, so the off-switch has quietly been unreachable.

Rather not hand-edit config files? SparkBox ships the VPN config with the right DNS switches already present, so this class of "invisible setting" problem never reaches you. See the walkthrough →

What's actually broken

First, a couple of definitions so the rest makes sense:

• DNS is the phone book of the internet — it turns a name like example.com into an IP address. If DNS fails, everything looks "down" even when the network is fine.
• DNS-over-TLS (DoT) is an encrypted version of those lookups. It's a privacy feature, but it only works if the resolver you're pointed at actually speaks DoT. If it doesn't, encrypted lookups get no answer and time out.
• .env is a plain-text configuration file where each line is a KEY=value setting the app reads at startup.

Version 1.6.317 introduced a switch to turn encrypted DNS off — that switch is the VPN_DOT variable. The problem: none of the things that are supposed to create config lines ever writes VPN_DOT=. Not install.sh, not setup.sh, and not the VPN modal in the web UI. So the key that would let you disable DoT was invisible on every box — fresh installs and upgrades alike. Without the line present, the off-switch has no effect, encrypted DNS stays forced on, and if your upstream can't do DoT, DNS silently dies.

This is exactly what issue #31768 was: a key nothing ever seeds, unreachable everywhere. The only workaround people had was to copy a hand-typed line out of the doctor output or the forum and append it to .env themselves.

The fix: write the VPN_DOT line yourself

Because the variable was never seeded, you add it once by hand. This is the same command the diagnostics tool and the forum have been handing out for #31768.

1. Open a terminal on the machine (or SSH session to the server) that runs your VPN, and change into the directory that contains its .env file — the same folder you ran the install/setup script from.

2. Append the off-switch line:

   echo 'VPN_DOT=off' | sudo tee -a .env

   That command adds a single line, VPN_DOT=off, to the end of the file. tee -a appends rather than overwriting, and sudo is there in case the file is root-owned. The command echoes the line back so you can confirm it went in.

3. Confirm the line is actually present:

   grep VPN_DOT .env

   You should see exactly VPN_DOT=off and nothing malformed. If you see it twice, you ran the append twice — delete the duplicate so there's only one.

4. Restart the VPN so it re-reads .env. Bring the service down and back up the same way you normally start it (for example your container stack's down/up, or the systemd service restart you use). Config in .env is only read at startup, so nothing changes until the process restarts.

5. Reconnect a client and test resolution. A quick name lookup is the cleanest proof:

   nslookup example.com

   If that returns an address now, plain DNS is flowing and the fix worked.

If DNS still fails after adding the line

Adding VPN_DOT=off fixes the specific case where encrypted DNS was forced on with no escape. If lookups still fail, walk these in order — they separate "DNS is broken" from "the tunnel is broken":

1. Confirm the process really restarted

The most common false negative is editing .env but never restarting, so the old config is still live in memory. Fully stop and start the VPN, then re-test. Check the startup logs for a line referencing DNS or DoT so you can see the new value being read.

2. Prove the tunnel itself is up

Ping an IP address directly (one you know, so no DNS is involved). If a raw IP is reachable but names aren't, the problem is purely DNS and the VPN_DOT fix is the right area. If even a raw IP fails, the tunnel or routing is the issue, not DNS — that's a different problem.

3. Re-check for a duplicate or conflicting line

If you or a previous forum copy-paste already added VPN_DOT somewhere, you can end up with two lines. The last one usually wins, but it's messy. Keep exactly one VPN_DOT=off and remove the rest.

Why this kept coming back

This wasn't a one-user mistake — it was structural. A setting shipped in v1.6.317, but the three places that write config (install.sh, setup.sh, and the VPN modal) never learned to write it. So every install was born without the switch, and every upgrade inherited the gap. The only path to the off-switch was a human copying a line from diagnostics or the forum, which is exactly the kind of invisible, undocumented step that leaves people stuck with "the VPN connects but DNS is dead" and no obvious reason why. That's the whole story behind #31768.

The durable fix is for a build to seed the line automatically. Until your install does, the manual echo above is the supported route — and it's the same one the doctor output points you to.

Frequently asked

Why is my VPN's DNS not resolving anything?

On installs from v1.6.317 onward, the encrypted-DNS off-switch is controlled by a VPN_DOT setting that was never written to your .env file. Because the line is absent, the toggle is unreachable and encrypted DNS (DNS-over-TLS) stays forced on. If your network or upstream resolver can't do DNS-over-TLS, name resolution fails silently. Adding VPN_DOT=off to .env and restarting restores it.

What does VPN_DOT actually control?

It's the switch for DNS-over-TLS, an encrypted form of DNS lookups. Setting it to off disables encrypted DNS so lookups fall back to plain DNS, which fixes resolution on networks or upstream resolvers that don't support DoT.

Do I need to add VPN_DOT even after upgrading?

Yes. Neither install.sh, setup.sh, nor the VPN modal ever writes a VPN_DOT= line, so fresh installs and upgrades are affected identically. The line has to be added to .env by hand until a build seeds it for you.

Will adding VPN_DOT=off make my DNS insecure?

It turns off DNS-over-TLS encryption for lookups only; your VPN tunnel itself is unaffected. If you specifically need encrypted DNS and your setup supports it, leave it on. This fix is for people whose DNS breaks because encrypted DNS is forced on with no reachable way to disable it.