---
name: pihole-troubleshooting
description: Diagnose Pi-hole v6 when devices lose internet — query the FTL database, identify false-positive blocks from deep CNAME inspection, and fix connectivity-domain failures.
---

# Pi-hole Troubleshooting

Triggers: "is Pi-hole working", "some devices have no internet", "DNS not resolving", "Pi-hole blocking too much", "devices can't connect after DNS change".

Pi-hole v6 stores all query history in a SQLite FTL database. Query it directly when the web UI is unreachable or you need raw data for pattern analysis.

## Quick health check

```bash
docker ps --format "table {{.Names}}\t{{.Status}}" | grep pihole
docker exec pihole pihole status
dig +short google.com @<pi-hole-ip>
```

## FTL database querying (Pi-hole v6)

The database is at `/etc/pihole/pihole-FTL.db` inside the container. Docker volumes typically live under `/var/lib/docker/volumes/pihole_etc/_data/pihole-FTL.db` but the `/var/lib/docker/` directory requires root to traverse — copy the DB out with sudo first:

```bash
sudo cp /var/lib/docker/volumes/pihole_etc/_data/pihole-FTL.db /tmp/pihole-FTL.db
sudo chown $USER:$USER /tmp/pihole-FTL.db
```

Then query with Python (sqlite3 is not in the Pi-hole container and may not be on the host):

```python
import sqlite3
conn = sqlite3.connect('/tmp/pihole-FTL.db')
```

### Key queries

**Recent activity by client:**
```sql
SELECT client, count(*) FROM queries 
WHERE timestamp > strftime('%s','now','-1 hour') 
GROUP BY client ORDER BY count(*) DESC;
```

**Check for blocked domains (status 1=gravity, 4=regex, 5=exact):**
```sql
SELECT domain, count(*) FROM queries 
WHERE timestamp > strftime('%s','now','-1 hour') AND status IN (1,4,5)
GROUP BY domain ORDER BY count(*) DESC LIMIT 20;
```

**Retry rate by client (>20% is suspicious):**
```sql
SELECT client, count(*) as total,
  sum(CASE WHEN status=17 THEN 1 ELSE 0 END) as retried,
  round(100.0 * sum(CASE WHEN status=17 THEN 1 ELSE 0 END) / count(*), 1) as pct
FROM queries WHERE timestamp > strftime('%s','now','-24 hours')
GROUP BY client HAVING total > 20 ORDER BY pct DESC;
```

### Pi-hole v6 status codes

| Code | Meaning |
|------|---------|
| 1 | Gravity block (adlist match) |
| 2 | Forwarded to upstream |
| 3 | Cache hit |
| 4 | Regex denylist block |
| 5 | Exact denylist block |
| 6 | Upstream block |
| 12 | Already forwarded (cached forward) |
| 14 | Cached as blocked (from prior CNAME-chain inspection) |
| 17 | Retried (first attempt failed, retry succeeded) |

Status 14 is the dangerous one — see Deep CNAME inspection pitfall below.

## Primary pitfall: Deep CNAME inspection false positives

**Symptoms:** Some devices lose internet after switching DNS to Pi-hole. Devices that do strict connectivity checks (Android TV, Windows NCSI) are most affected. Pi-hole health check passes, DNS resolves fine from the server, but client devices think there's no internet.

**Root cause:** When `CNAMEdeepInspect = true` (default in v6), Pi-hole follows CNAME chains. If ANY domain in the chain matches a blocklist entry, the ENTIRE chain is cached as blocked (status 14). Common false-positive domains:

- `connectivitycheck.gstatic.com` (Android TV/Shield connectivity check)
- `dns.msftncsi.com` (Windows NCSI connectivity check)
- `ota.nvidia.com` (Shield TV updates)
- `clients3.google.com`, `android.apis.google.com` (Google Play Services)

The blocklists (e.g., StevenBlack) include subdomains like `pagead.l.google.com` — these are ad-specific, but deep CNAME inspection propagates the block up the chain to the parent `l.google.com`, which kills ALL services using Google infrastructure.

**Detection:** Query the FTL database for status 14 on these domains:

```sql
SELECT domain, count(*) FROM queries WHERE status=14 
GROUP BY domain ORDER BY count(*) DESC LIMIT 20;
```

If `connectivitycheck.gstatic.com`, `dns.msftncsi.com`, or `google.com` appear here → deep CNAME inspection is the cause.

**Fix — whitelist the critical domains (preferred):**

```bash
# Pi-hole v6: use 'allow', NOT 'pihole -w' (that's v5 syntax, broken)
docker exec pihole pihole allow connectivitycheck.gstatic.com
docker exec pihole pihole allow dns.msftncsi.com
docker exec pihole pihole allow clients3.google.com
docker exec pihole pihole allow ota.nvidia.com
docker exec pihole pihole allow android.apis.google.com

# Google Cast / Chromecast: mtalk domains break casting on Android TV & Shield
docker exec pihole pihole allow alt1-mtalk.google.com
docker exec pihole pihole allow alt2-mtalk.google.com
docker exec pihole pihole allow alt3-mtalk.google.com
docker exec pihole pihole allow alt4-mtalk.google.com
docker exec pihole pihole allow alt5-mtalk.google.com
docker exec pihole pihole allow alt6-mtalk.google.com
docker exec pihole pihole allow alt7-mtalk.google.com
docker exec pihole pihole allow alt8-mtalk.google.com

# Flush the DNS cache so cached blocks are cleared
docker exec pihole pihole reloaddns
```

**Alternative fix — disable deep CNAME inspection:**

Edit `/etc/pihole/pihole.toml` or set via environment: `CNAMEdeepInspect = false`. This stops the false positives but may allow some CNAME-cloaked ad/tracking domains through.

## Other diagnostic checks

**Is the device even on the network?**
```bash
ping -c 3 <device-ip>
ip neigh show <device-ip>   # Check ARP status
```
STALE = was recently seen, FAILED = unreachable, REACHABLE = online.

**Is Pi-hole rate-limiting?**
```bash
docker exec pihole grep -i 'rate.limit' /var/log/pihole/FTL.log | tail -10
```
Default: 1000 queries per 60 seconds per client. If triggered, increase the limit or investigate the noisy client.

**Check upstream DNS latency:**
```bash
dig +time=3 google.com @8.8.8.8        # Direct to upstream
dig +time=3 google.com @<pi-hole-ip>   # Via Pi-hole
```
Upstream latency > 100ms can cause Pi-hole to retry queries (status 17).

## Docker-specific notes

Pi-hole v6 container: `pihole/pihole:latest` (or dated tag). Container is minimal Alpine — no python3, no sqlite3. Query the DB from the host.

Find the database volume:
```bash
docker inspect pihole --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}'
```