Introduction

The Traefik dashboard provides a web interface to monitor routers, services, middlewares, and overall traffic patterns. When the dashboard becomes inaccessible, you lose visibility into your routing configuration and traffic flow. Common issues include disabled API, missing ingress configuration, authentication problems, or network policies blocking access.

Symptoms

Error messages when accessing dashboard:

bash
404 page not found
403 Forbidden
Connection refused
ERR_CONNECTION_REFUSED
Unauthorized

Observable indicators: - Dashboard URL returns 404 error - Browser cannot connect to dashboard port - API endpoints return empty responses - Authentication fails or loops - Dashboard shows but no data populates

Common Causes

  1. 1.API not enabled - Dashboard requires API to be configured
  2. 2.Wrong endpoint - Accessing wrong URL or port
  3. 3.Insecure mode disabled - Production requires secure router
  4. 4.Missing router configuration - No IngressRoute for dashboard
  5. 5.Network policy blocking - Kubernetes NetworkPolicy or firewall
  6. 6.Authentication middleware missing - Dashboard unprotected or misconfigured
  7. 7.Port not exposed - Docker port not mapped
  8. 8.TLS/SSL issues - Certificate problems blocking access

Step-by-Step Fix

Step 1: Check if API and Dashboard are Enabled

```bash # Check Traefik configuration docker exec traefik cat /etc/traefik/traefik.yml

# Check running Traefik flags docker exec traefik ps aux | grep traefik

# Check API endpoint curl http://localhost:8080/api/overview curl http://localhost:8080/api/http/routers

# Check Kubernetes deployment kubectl get deployment traefik -n traefik -o yaml | grep -A20 args ```

Step 2: Enable API and Dashboard

```yaml # traefik.yml - Static configuration api: dashboard: true insecure: true # Only for development! Not for production

# Or via command line # traefik --api.dashboard=true --api.insecure=true ```

yaml
# docker-compose.yml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.dashboard=true"
      - "--api.insecure=true"  # Development only
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"  # Dashboard port

```yaml # Kubernetes - Helm values # values.yaml api: dashboard: true insecure: false # Use secure router instead

ports: traefik: port: 9000 expose: true ```

Step 3: Configure Secure Dashboard Access (Production)

yaml
# docker-compose.yml - Secure dashboard with labels
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls=true"
      - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=auth"
      - "traefik.http.middlewares.auth.basicauth.users=admin:$$apr1$$..."
yaml
# Kubernetes IngressRoute for dashboard
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: dashboard
  namespace: traefik
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`traefik.example.com`)
      kind: Rule
      services:
        - name: api@internal
          kind: TraefikService
      middlewares:
        - name: auth
  tls:
    secretName: traefik-dashboard-tls

Step 4: Fix Port Exposure

```bash # Check if port is exposed docker port traefik

# Should show: # 8080/tcp -> 0.0.0.0:8080

# For Kubernetes kubectl get svc traefik -n traefik kubectl port-forward svc/traefik 8080:9000 -n traefik ```

yaml
# Docker Compose - expose dashboard port
services:
  traefik:
    ports:
      - "8080:8080"  # Dashboard on port 8080

Step 5: Configure Basic Authentication

```bash # Generate password hash apt-get install apache2-utils # Debian/Ubuntu htpasswd -nB admin

# Output: admin:$2y$05$...

# For traefik, escape $ with $$ # admin:$$2y$$05$$... ```

yaml
# Docker labels with basic auth
labels:
  - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$apr1$$H8DQvWEG$$vXkPvPFfP7nGKh.Q7mJUZ/"
  - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
yaml
# Kubernetes Middleware for basic auth
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: dashboard-auth
  namespace: traefik
spec:
  basicAuth:
    users:
      - admin:$apr1$H8DQvWEG$vXkPvPFfP7nGKh.Q7mJUZ/

Step 6: Check Network Connectivity

```bash # Test local connectivity curl -v http://localhost:8080/api/overview curl -v http://localhost:8080/dashboard/

# From inside container docker exec traefik wget -qO- http://localhost:8080/api/overview

# Check firewall sudo iptables -L -n | grep 8080 sudo ufw status

# For Kubernetes, check NetworkPolicy kubectl get networkpolicy -n traefik kubectl describe networkpolicy -n traefik ```

Step 7: Fix Kubernetes Service Access

yaml
# Ensure Traefik service exposes dashboard port
apiVersion: v1
kind: Service
metadata:
  name: traefik
  namespace: traefik
spec:
  type: LoadBalancer
  ports:
    - port: 80
      name: web
      targetPort: web
    - port: 443
      name: websecure
      targetPort: websecure
    - port: 8080
      name: dashboard
      targetPort: traefik
  selector:
    app.kubernetes.io/name: traefik

```bash # Port-forward for testing kubectl port-forward -n traefik svc/traefik 8080:8080

# Access via port-forward curl http://localhost:8080/api/overview ```

Step 8: Verify Dashboard Access

```bash # Check API health curl http://localhost:8080/api/overview

# Expected response: # {"PPP":...,"http":...}

# Access dashboard in browser # http://localhost:8080/dashboard/

# Note the trailing slash is required!

# Check router for dashboard curl http://localhost:8080/api/http/routers | jq '.[] | select(.name | contains("dashboard"))' ```

Advanced Diagnosis

Debug API Issues

yaml
# Enable debug logging
log:
  level: DEBUG
api:
  dashboard: true
  debug: true  # Enable debug endpoint
bash
# Access debug endpoint
curl http://localhost:8080/debug/health
curl http://localhost:8080/debug/pprof/

Check with Different Browsers

```bash # Test with curl to rule out browser issues curl -v http://localhost:8080/dashboard/

# Check for CORS issues curl -H "Origin: http://example.com" -v http://localhost:8080/api/overview

# Check with authentication curl -u admin:password http://localhost:8080/api/overview ```

Dashboard Not Loading Data

```bash # Check if providers are working curl http://localhost:8080/api/providers

# Should show Docker/Kubernetes/File providers

# Check if routers exist curl http://localhost:8080/api/http/routers | jq

# Check if services exist curl http://localhost:8080/api/http/services | jq ```

WebSocket Issues

```yaml # Dashboard uses WebSocket for live updates # Ensure WebSocket connections work

# Check Traefik entrypoint for WebSocket entryPoints: websecure: address: ":443" http: tls: {} ```

bash
# Test WebSocket connectivity
# Open browser console on dashboard page
# Check for WebSocket errors

Common Pitfalls

  • Missing trailing slash - Dashboard URL requires trailing slash: /dashboard/
  • Insecure mode in production - Never use api.insecure=true in production
  • No authentication - Exposing dashboard without auth is security risk
  • Wrong service name - Must use api@internal as service
  • Port conflict - Dashboard port already in use by another service
  • TLS termination - Dashboard behind reverse proxy may need TLS disabled

Best Practices

```yaml # Complete secure dashboard configuration # traefik.yml api: dashboard: true insecure: false # Never expose without authentication in production

log: level: INFO ```

```yaml # docker-compose.yml with secure dashboard version: "3.8"

services: traefik: image: traefik:v3.0 command: - "--api.dashboard=true" - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" - "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443" - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com" - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json" - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web" ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt labels: - "traefik.enable=true" # Dashboard router - "traefik.http.routers.dashboard.rule=Host(traefik.example.com)" - "traefik.http.routers.dashboard.entrypoints=websecure" - "traefik.http.routers.dashboard.tls=true" - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt" - "traefik.http.routers.dashboard.service=api@internal" # Basic auth middleware - "traefik.http.middlewares.dashboard-auth.basicauth.users=${DASHBOARD_USER}:${DASHBOARD_PASS}" - "traefik.http.routers.dashboard.middlewares=dashboard-auth" environment: - DASHBOARD_USER=admin - DASHBOARD_PASS=$$apr1$$... ```

yaml
# Kubernetes secure dashboard with OAuth
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: dashboard
  namespace: traefik
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`traefik.example.com`)
      kind: Rule
      services:
        - name: api@internal
          kind: TraefikService
      middlewares:
        - name: oauth-auth
          namespace: traefik
  tls:
    secretName: traefik-dashboard-tls
  • Traefik Start Failed
  • Traefik Configuration Error
  • Traefik Auth Basic Error
  • Traefik Routing Not Working