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.