Wi-Fi & Network

Pi-hole broke after the v6 upgrade

Web UI 404, custom dnsmasq rules ignored, settings 'lost' — the v5→v6 rewrite changed the web server and config files. Recover cleanly.

Problem summary

Pi-hole v6 replaced the lighttpd/PHP web stack with a web server built into pihole-FTL and unified settings into pihole.toml. Most post-upgrade breakage is one of three things: the admin URL/port changed, /etc/dnsmasq.d snippets are no longer read, or settings appear lost because they migrated.

Operator snapshotEvidence first

First proof

Check whether DNS still resolves for clients, separate from the dashboard.

Screen to open

sudo systemctl status pihole-FTL (or: docker logs <pihole-container>)

Expected signal

Clients can browse and lookups appear in Pi-hole's log even if the admin page is down.

Stop boundary

If you reinstall, restore the Teleporter backup afterward or you'll lose lists, groups, and local records.

Layer path

1Pi-hole v6 (the February 2025 rewrite) made two changes that cause most post-upgrade surprises: the admin UI now comes from a web server built into pihole-FTL (no more lighttpd/PHP), and all settings live in a single /etc/pihole/pihole.toml.

2Three failure shapes dominate: the admin URL/port behaves differently (404 or a port clash), hand-edited /etc/dnsmasq.d snippets are no longer read by default, and settings look 'lost' because they were migrated into the toml.

3DNS resolution and admin access are separate concerns — v6 can be resolving correctly for clients while the dashboard is unreachable, and vice versa. Diagnose them independently.

4Treat the migration as authoritative: edit pihole.toml going forward, not the old setupVars.conf/pihole-FTL.conf, which v6 reads once and then ignores.

Runbook

Step-by-step runbook

Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.

Back up before you change anything

Check: Export a Teleporter backup (Settings > Teleporter) if the UI is reachable, or copy /etc/pihole aside on the host.

Expected result: You have a restore point for lists, groups, allow/deny rules, and local DNS records.

If not: If the UI is down, copy the /etc/pihole directory from the shell before editing.

Split DNS health from admin health

Check: Test resolution with dig/nslookup against the Pi-hole IP, separately from loading the dashboard.

Expected result: You know which half is broken — resolver vs web UI.

If not: If DNS is fine, leave upstreams alone and focus on the web server/port.

Get the dashboard back

Check: Confirm FTL is running, hit /admin on the FTL web port, and clear any port-80 conflict with another web service or reverse proxy.

Expected result: The admin UI loads from FTL's built-in server.

If not: If a reverse proxy must keep port 80, point it at FTL's configured port instead.

Restore custom dnsmasq behavior

Check: If static leases or extra local DNS records vanished, set misc.etc_dnsmasq_d in pihole.toml to re-include /etc/dnsmasq.d, then restart FTL.

Expected result: Your hand-added records apply again.

If not: Confirm the syntax against the current v6 docs before relying on it.

Reconcile settings in pihole.toml

Check: Compare the migrated toml against what you expect; reconfigure only genuine gaps via the UI or the toml.

Expected result: Settings match your intended config without a destructive reinstall.

If not: Avoid re-running the installer/setup repeatedly — double-configuring FTL creates new, harder problems.

Re-verify end to end

Check: From a client, confirm resolution and that blocked domains are still blocked; confirm the dashboard logs queries.

Expected result: Resolver and admin UI are both healthy and consistent.

If not: If anything is still off, restore the Teleporter backup rather than layering more edits.

Decision tree

If: DNS resolves for clients but the admin page 404s.

Then: Web-server/port problem, not a resolver problem.

Action: Verify FTL is up, hit /admin on FTL's web port, and resolve any port-80 clash with another service.

If: Neither DNS nor the dashboard works.

Then: pihole-FTL likely isn't running or failed to start.

Action: Restart FTL and read its log; a malformed pihole.toml or a bound-port conflict will be reported there.

If: Custom static leases / local DNS records disappeared.

Then: /etc/dnsmasq.d is no longer auto-included in v6.

Action: Set misc.etc_dnsmasq_d in pihole.toml to re-include it, then restart FTL.

If: Settings appear blank after the upgrade.

Then: They were migrated into pihole.toml, not lost.

Action: Inspect the toml and the query log; reconfigure only what's genuinely missing rather than reinstalling.

Safe stop: If you reinstall, restore the Teleporter backup afterward or you'll lose lists, groups, and local records.

Evidence

Evidence table

Symptom	Evidence to collect	Likely layer	Next action
Admin page 404 but internet works.	FTL service status; what process is listening on port 80.	Built-in FTL web server / port clash	Move the conflicting web service or set FTL's web port; reach the dashboard at /admin.
Both DNS and dashboard dead after upgrade.	pihole-FTL startup log.	FTL not running / bad config	Fix the reported config or port error, restart FTL, re-test resolution first.
Static leases / custom records gone.	Whether /etc/dnsmasq.d is included (misc.etc_dnsmasq_d).	v6 dnsmasq.d default-off	Re-enable inclusion in pihole.toml and restart FTL.
Dashboard shows defaults / empty.	Contents of /etc/pihole/pihole.toml.	Migrated settings, not data loss	Read the toml; reconfigure only true gaps; avoid a blind reinstall.

Reference

Commands and settings paths

Is FTL running?

sudo systemctl status pihole-FTL (or: docker logs <pihole-container>)

Where: On the Pi-hole host or container.

Expected: FTL is active/running with no fatal config errors in the recent log.

Failure means: A stopped or crash-looping FTL takes down both DNS and the admin UI.

Safe next step: Read the log line that names the failing setting or bound port, then correct pihole.toml.

What owns port 80?

sudo ss -ltnp | grep ':80'

Where: On the Pi-hole host.

Expected: pihole-FTL is the listener on the web port (or your chosen port).

Failure means: Another web server / reverse proxy on port 80 will block FTL's built-in UI.

Safe next step: Move the other service or set FTL's web port in pihole.toml, then reload.

Confirm DNS independently of the UI

dig @<pi-hole-ip> example.com (or nslookup example.com <pi-hole-ip>)

Where: From any LAN client.

Expected: Pi-hole answers the query, proving the resolver is healthy regardless of the dashboard.

Failure means: If this fails too, the problem is FTL/DNS, not just the web UI.

Safe next step: Triage FTL startup before spending time on the admin page.

Check the migrated config

sudo less /etc/pihole/pihole.toml

Where: On the Pi-hole host.

Expected: Your interface, upstreams, and the misc.etc_dnsmasq_d setting are present and correct.

Failure means: Editing the old setupVars.conf/pihole-FTL.conf has no effect in v6 — they're read once at migration.

Safe next step: Make changes in pihole.toml (or via the UI) and restart FTL.

Hardware boundary

Hardware and platform boundary

Change only when

Plan the v6 upgrade deliberately: read the official v5→v6 notes for your platform (bare metal vs Docker) first, and take a Teleporter backup before starting.

Evidence that matters

Whether anything else on the host uses port 80, whether you rely on /etc/dnsmasq.d snippets, and that you'll manage settings in pihole.toml afterward.

Evidence that does not matter

The exact old config filenames — they're migrated and then ignored; memorizing setupVars.conf paths doesn't help post-v6.

Avoid

Reinstalling as a first reflex (you'll lose lists/groups/records without a restore), or editing setupVars.conf expecting v6 to read it.

Related tool/checklist

Use the linked tool when you need a guided plan from your exact symptoms instead of a static checklist.

Device setup troubleshooter

Last reviewed

2026-06-02 · Reviewed by HomeTechOps. Built from June-2026 research verified against Pi-hole's official 'Introducing v6' post and the Docker v5→v6 upgrade docs; the embedded-FTL web server, the /etc/dnsmasq.d default-off change, and the pihole.toml migration are the documented v6 behaviors. Specific deprecated CLI flags were intentionally left out pending first-party confirmation.

Sources/assumptions

Assumes an in-place upgrade from Pi-hole v5 to v6 (the February 2025 rewrite) on bare metal or Docker.
v6 settings live in /etc/pihole/pihole.toml; the old setupVars.conf and pihole-FTL.conf are migrated on upgrade, not edited going forward.
Confirm the exact current version and any deprecated CLI flags against the official v6 docs before scripting against the new release.

Source-backed checks

HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.

Apple Support: Wi-Fi and internet troubleshooting on MacUsed for safe first checks around Wi-Fi status, diagnostics, VPN/security software, and external network devices.Microsoft Support: Fix network connection issues in WindowsUsed for Windows network baseline checks before changing router-wide settings.Pi-hole: Introducing Pi-hole v6Used for the v6 architecture change — the embedded FTL web server replacing lighttpd/PHP, the REST API, and Lua admin pages.Pi-hole docs: Upgrading from v5 to v6 (Docker)Used for the v5→v6 migration behavior, including that /etc/dnsmasq.d is no longer read by default and the move to pihole.toml.Pi-hole: Core releases (GitHub)Used to date-stamp the current Pi-hole Core/FTL/Web versions rather than asserting a frozen version number.Pi-hole documentationUsed as the first-party reference for Pi-hole install, configuration, and the v6 documentation set.

Diagnostic rule

1. Check the simplest signal first.
2. Change one thing at a time.
3. Avoid unsafe electrical or data-loss steps.
4. Stop when the evidence says the risk moved.

FAQ

After upgrading to v6 the admin page is a 404 — did the install fail?

Usually not. v6 dropped lighttpd and now serves the admin UI directly from pihole-FTL, with the dashboard under `/admin` on the FTL web port. If you previously ran another web server (or a reverse proxy) on port 80, it can now collide with FTL's built-in server. Check that pihole-FTL is running, hit `http://<pi-hole-ip>/admin`, and if a separate web server owns port 80, set FTL's port in pihole.toml or move the other service.

My custom rules in /etc/dnsmasq.d stopped working after v6 — why?

v6 does not read `/etc/dnsmasq.d/` by default anymore. Custom dnsmasq snippets (static leases, extra `cname`/`address` records, conditional forwarding you hand-edited) silently stop applying. Re-enable inclusion via the `misc.etc_dnsmasq_d` setting in pihole.toml (or the matching mount/env in Docker), then restart FTL. Confirm in the official v5→v6 upgrade docs for your platform before relying on it.

All my settings look gone after the upgrade — are they lost?

Almost always migrated, not lost. v6 reads your old `setupVars.conf` once and writes the equivalent into `/etc/pihole/pihole.toml`, then stops using the old file. If the dashboard looks empty, you're likely looking at a fresh login/session or the wrong instance — re-check the toml and the query log. Don't re-run setup or re-import blindly; you can double-configure and confuse FTL.

Should I just reinstall instead of fixing the v6 upgrade?

Only as a last resort, and back up first (Settings > Teleporter export). Most v6 upgrade problems are the port/admin-URL change, the dnsmasq.d default, or a stale browser session — all fixable in place. A reinstall loses your blocklists, allow/deny rules, groups, and local DNS records unless you restore the Teleporter archive afterward.