Skip to content
Documentation
v3 (Preview)
Troubleshooting (v2)

Troubleshooting (v2)

Docker provider

  1. Verify tsdproxy.enable=true
  2. Check port labels: Port config
  3. For HTTPS targets: tsdproxy.port.1: "443/https:443/https"
  4. Self-signed certs: add no_tlsvalidate option
  5. Check firewall
  6. Same Docker network as TSDProxy
  7. Network issues: use tsdproxy.autodetect: "false" label and specify port explicitly

Lists provider

  1. Config is case-sensitive: Verify files
  2. Check file path in lists: config

Common Errors

TLS certificate errors (self-signed)

Docker: tsdproxy.port.1: "443/https:443/https, no_tlsvalidate" Lists: Set tlsValidate: false on the port

Network timeout

Firewall fix: sudo ufw allow in from 172.17.0.0/16

Funnel doesn’t work

Enable in ACL, add tailscale_funnel port option. See Funnel Security for details.

Proxy stuck “Authenticating”

Verify OAuth credentials or AuthKey. Check logs. See Authentication Methods for setup.

Dashboard unreachable after upgrading to v2.2.0

v2.2.0 changed the default http.hostname from 0.0.0.0 to 127.0.0.1 for security (see GHSA-j8rq-87gr-gm9q). If you expose the dashboard via Docker port mapping (ports: "8080:8080"), the server only listens on localhost inside the container — unreachable from the host.

When running in Docker, the hostname is automatically overridden to 0.0.0.0, so no manual configuration is needed.

For non-Docker setups, set hostname explicitly in your tsdproxy.yaml:

http:
  hostname: 0.0.0.0
  port: 8080

“Access requires a Tailscale connection” on dashboard

v2.2.0 requires authentication on all dashboard endpoints. If you access the dashboard through Docker port mapping (not via a Tailscale proxy), there is no Tailscale identity to authenticate with.

Fix: enable localhost access in your tsdproxy.yaml:

adminAllowLocalhost: true

When adminAllowLocalhost is enabled, requests from loopback (127.0.0.0/8) and RFC 1918 private networks (including Docker bridge IPs like 172.17.0.1) are trusted. This works correctly with Docker port mapping out of the box.

⚠️ Anyone who can reach port 8080 on your host will have admin access. If the port is exposed to a network, consider restricting it or using an API key instead.

See Admin Allowlist for details.

Enabling debug logging 

log:
  level: trace

Custom domain setup fails

Check the logs for specific errors:

  • waiting for proxy URL: timeout — Tailscale proxy took too long to start. Verify auth credentials and network connectivity.
  • tls provider "..." not found — The provider name in defaultTLSProvider or the per-proxy tlsprovider label must match a key in tlsProviders.
  • dns provider "..." not found — Same as above for dnsProviders.
  • no cloudflare zone found for ... — The domain’s DNS is not managed by the Cloudflare account linked to the API token.

See Custom Domains for the full troubleshooting guide.

Last updated on
SecurityFrequently Asked Questions