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.

1 Like

Failed installation
Pi-hole DNS not resolving
Guide for less problematic setup?
Sneaky Query... how did this happen?
Ads not blocked from Ubuntu VM after install. Perhaps router configuration?
pihole-FTL is working, but webmin says the service is not running
Pi-Hole update error to V4.0
Update error: unable to resolve reference refs/tags/v4.0: Invalid argument
Pi-Hole Not Blocking YouTube Ads IOS
Pi-Hole crashes
Connecting via ethernet with Pi-Hole starter kit
Localhost Querying Pihole domain?
Problems 0 domains on fresh install?
Not blocking ads
New user, Pi1 with latest Raspbian is glacially slow
RaspAP && PiHole
DHCP Server Trouble
FTL Offline
Fritzbox antwortet
DHCP on Connect Box (UPC) IPv4 - Help
Pi hole working (sort of, but not all the time!)
Mit pi-hole werden Seiten oft erst beim zweiten Aufruf geladen
Top blocked domain not showing any clients
Can't update pihole
Configure DNS at TP-LINK VR600
Configure DNS at TP-LINK VR600
PHP error with 4.0
Updated to v4.0 and now whitelist isn't working
Wifi Bridge With Dnsmasq
Debug log gives strange values for number of domains in Gravity
/var/log in Top Permitted Domains
Downloading and Installing FTL... freeze on installation debian 9.4
Query Log empty 3.3.1
Pi-hole through VPN not working
FTLDNS stops working
Possible BUG with API_QUERY_LOG_SHOW icw Web admin
Website Blocked "Not found on any Blacklist" (
Clients Chart Not Loading (Spinning Wheel)
Fetching branches fails
Pi-Hole is not working? why not
Pi hole server in VM with two network interfaces
Router / Pihole IPv6 adresses
IPV6 pihole block page gives error, IPV4 works ok. Admin page works on IPV6 and IPV4
FTL is offline, but pihole works
DHCP server gives out wrong IP for DNS
High CPU load, no graphs
Your debug token is: Use netcat
Long-term queries over time: Inconsistency
Default Ad-Servers from list are not being installed
Webpages are really slow or even not loading. windows 10, chrome
PiVPN + Pi-Hole installation let crashes the Raspberry
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?
Pi-hole v3.2 Introduces Long-term Statistics, An Audit Log, Colours, and More!
The results of pi-hole are scary part II
Pi-Hole as DHCP - clients not getting IP
SqLite3 and json_encode() fault
PiHole help
DNS breaks when installing Pihole
DHCP läuft aber verbindet nicht.
Unable to install pi-hole - bash: curl: command not found
Pi-Hole (FTL) crashes every few hours :(
pihole-FTL service running but not functioning
Update fehlgeschlagen