How do I debug my Pi-hole installation?

Method 1: Generate a debug token via the Web interface

  1. Log in to your Pi-hole's Web interface
  2. Navigate to Tools > Generate debug log
  3. Click the Generate debug log button
  4. Send us the debug token

Method 2: Use the command line to generate a debug token

  1. Login into your Pi-hole's command line
  2. Enter pihole -d
  3. Provide us with the debug token that is generated after the debug script completes

Alternative: Securely sending us additional information

Preferred Method

If there is additional information you want to provide us, you can upload any kind of text to our server. You will still get a debug token so your information will remain anonymous.

To do this, you can pipe some shell output into netcat, which will upload it to our secure server.

Here are a few examples of how you can send us this information:

VIa The pihole Command (assuming your install is not broken and the pihole command exists)

echo "hello developers" | pihole tricorder
cat some.log | pihole tricorder

pihole tricorder will always use openssl if it is available. If it's not, it will revert to using netcat.

Via NetCat (cleartext)

echo "some text" | nc 9999
cat somefile.txt | nc 9999
tail -n4 /var/log/pihole.log | nc 9999

Via SSL (encrypted)

echo "Information to send over SSL" | openssl s_client -quiet -connect 2> /dev/null

Be patient as it can sometime take a moment for it to upload. Once complete, you will receive a debug token such as 3vnm3hqwjs:

root@ubuntu:~$ echo "help me" | nc 9999

When you are ready to get some help from us, give us this token and we can look up your information. Please note anything uploaded will self-destruct after 48 hours.

Alternate Methods

These services are similar, but your information will be more public. Just send us the link generated from the service.

Pi-hole DNS not resolving
Failed installation
Guide for less problematic setup?
Sneaky Query... how did this happen?
Ads not blocked from Ubuntu VM after install. Perhaps router configuration?
Pi-hole v3.2 Introduces Long-term Statistics, An Audit Log, Colours, and More!
Your debug token is: Use netcat
High CPU load, no graphs
DHCP server gives out wrong IP for DNS
FTL is offline, but pihole works
IPV6 pihole block page gives error, IPV4 works ok. Admin page works on IPV6 and IPV4
Router / Pihole IPv6 adresses
Pi hole server in VM with two network interfaces
The results of pi-hole are scary part II
Fetching branches fails
Clients Chart Not Loading (Spinning Wheel)
Website Blocked "Not found on any Blacklist" (
Possible BUG with API_QUERY_LOG_SHOW icw Web admin
FTLDNS stops working
Pi-hole through VPN not working
Query Log empty 3.3.1
Downloading and Installing FTL... freeze on installation debian 9.4
/var/log in Top Permitted Domains
What do debug logs contain?
Wifi Bridge With Dnsmasq
Updated to v4.0 and now whitelist isn't working
Configure DNS at TP-LINK VR600
Configure DNS at TP-LINK VR600
Can't update pihole
Unable to install pi-hole - bash: curl: command not found
Top blocked domain not showing any clients
Mit pi-hole werden Seiten oft erst beim zweiten Aufruf geladen
Pi hole working (sort of, but not all the time!)
DHCP on Connect Box (UPC) IPv4 - Help
Update fehlgeschlagen
Fritzbox antwortet
FTL Offline
DHCP Server Trouble
RaspAP && PiHole
New user, Pi1 with latest Raspbian is glacially slow
Not blocking ads
Problems 0 domains on fresh install?
pihole-FTL service running but not functioning
Localhost Querying Pihole domain?
Connecting via ethernet with Pi-Hole starter kit
Pi-Hole crashes
Pi-Hole Not Blocking YouTube Ads IOS
Update error: unable to resolve reference refs/tags/v4.0: Invalid argument
Pi-Hole (FTL) crashes every few hours :(
Pi-Hole update error to V4.0
DHCP läuft aber verbindet nicht.
DNS breaks when installing Pihole
PiHole help
Pi-Hole as DHCP - clients not getting IP
Pi-hole, Subdomain in DNS web-ui is crippled, going in via ip address is ok
Pi-Hole is not working? why not
Pi-Hole not working with Bell 1000 router
DNS resolution issues- non-blocked sites
FTL will nicht updaten wegen Lighttpd fail
Pi hole only blocking 12%
Problem with pihole used inside a network with DC 2012 Server
Long Term Data Not Displaying
No DNS resolution after install
DHCP setup didn't work - Entire network went dark
DHCP setup didn't work - Entire network went dark
One client shows no query results on the Web UI, just an error message
Webseite ist Kaputt
Pihole keine "querries blocked" mit unifi Netzwerk
Device does not use Pi-hole
setup on pace 5286AV
Queries over last 24 hours & Clients (over time) are empty
Web Interface not reachable with ipaddress, refused connection
Pihole in a Synology AD Domain
Pi Hole Update - Fehler
Unbound connection problems
PiHole DNS my laptop wont be accepted as client
Weird Timeout Issues
Erreur PHP
Pi-hole not blocking ads but active
Pi1 problem
Update old version
High Load bei wenig CPU last
Long-term queries over time: Inconsistency
Phone doesn't seem to use pihole dns for much
Pihole Update Confirmation
Web Interface aktualisiert nicht trotz Neuinstallation
Pi Hole setzt sich zurück
Werbe-Grafiken der Hauptdomain blocken
PiHole constantly runs at over 100% CPU utilization and is virtually unusable
Webinterface nicht erreichbar
Stuborn wont get blocked
DHCP Problem
Off-net requests are not answered
Probleme mit der Netzwerkverbindung / DNS Server
DNS/DHCP server is not working after a restart
Devices Not Using Pi-Hole With DHCP Enabled
what do i use for dns
Was bedeutet die kontrolleuchte Staus "Load"
Generic raspberry pi setup fails update
Unknown clients making requests
Cont: website circumvents adblocking
Web interface not working, lighttpd does not work
PiHole läßt mich auf keine Website mehr
FTL Engine not installed
Migration of Whitelists to Blacklist
Connection lost to website sometimes
Not getting replies from the internet when the router's DNS is Pi-hole
Admin console/ssh stops working shortly after boot, only if it is acting DNS server
Can no longer access Admin page
Pihole problem
Default Ad-Servers from list are not being installed
Issues with PiHole (dnsmasq) DHCP - no leases left
Web won't update to 5 beta
Cname not decoded
Pi-hole installation failure on Jetson TX2
DNS-over-HTTPS not working(?)
restore lightpd to serve pi-hole
Secondary VLAN resolving DNS query without PiHole
DNS resolution breaks when temporarily disabling Pi-Hole 5
Conditional Forwarding stops working when I reboot host or restart container
PiHole 5 suddenly stops to resolve DNS requests
PiHole 5 suddenly stops to resolve DNS requests
Pi Hole freezes in dhcp mode
Probleme nach Update: Hohe RAM-Belegung und Chronometer geht nicht mehr
Pi-hole doesn't resolve the right DNS
Webpages are really slow or even not loading. windows 10, chrome
PiVPN + Pi-Hole installation let crashes the Raspberry
pihole-FTL is working, but webmin says the service is not running
Pihole have no log files
Why do blacklisted domains show IPv4 as "Pi-holed" but not IPv6 in the query log?
Pihole 3.0 on Synology Docker - list updates fail
PiVPN + Pi-Hole installation let crashes the Raspberry
Unknown Error -1
Sneaky Query... how did this happen?