From 5e85f3b3d8cd3d7f5dd4af8cee9e82002993c788 Mon Sep 17 00:00:00 2001 From: Goodness Nwajichukwu Date: Fri, 6 Feb 2026 17:47:59 +0100 Subject: [PATCH] Add environment-level troubleshooting guide for API authentication This guide helps developers troubleshoot API authentication issues that are not caused by Pi-hole itself but by environment-level factors. It covers common causes such as: - Port conflicts - Reverse proxy interference - Local DNS overrides - Container networking issues - Firewall blocking The goal is to reduce unnecessary debugging, improve developer experience, and prevent support tickets caused by setup issues rather than the Pi-hole API. Signed-off-by: Goodness Nwajichukwu --- docs/-troubleshooting.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 docs/-troubleshooting.md diff --git a/docs/-troubleshooting.md b/docs/-troubleshooting.md new file mode 100644 index 000000000..9bbe4c041 --- /dev/null +++ b/docs/-troubleshooting.md @@ -0,0 +1,19 @@ +--- + +## Environment-Level Troubleshooting for API Issues + +In some cases, API authentication or connectivity errors may not originate from Pi-hole itself, but from the local system or network environment. Before assuming the API is malfunctioning, check the following common setup issues. + +### Common Causes + +| Issue | Description | What to Verify | +|------|-------------|----------------| +| Port conflicts | Another service may already be using ports required by Pi-hole (commonly 80 or 443). | Stop other local web servers or check active ports using system tools. | +| Reverse proxy interference | Reverse proxies (e.g., Nginx, Apache, Traefik) may modify headers or routes. | Review proxy configuration and ensure API requests are forwarded correctly. | +| Local DNS overrides | Entries in `/etc/hosts` or custom DNS rules may redirect requests incorrectly. | Confirm that the API hostname resolves to the correct IP address. | +| Container networking issues | In container setups, using `localhost` instead of the service name can cause connection failures. | Use the container service name within Docker networks. | +| Firewall restrictions | Local firewall rules may block internal API communication. | Temporarily disable firewall rules to test connectivity. | + +### Why This Check Is Important + +These environment-level issues can produce errors that resemble API failures, even when Pi-hole is functioning normally. Verifying the local setup first can help reduce unnecessary troubleshooting and support requests.