Troubleshooting

Troubleshooting

This section covers common issues you might encounter while setting up or running the UniFi Dashboard.

Connectivity and Credential Issues

Most dashboard errors are related to incorrect environment configuration or network reachability to the UniFi API.

"UNIFI_API_KEY environment variable is required"

The server will fail to start if the API key is missing.

• Cause: The .env file is missing, renamed incorrectly, or the UNIFI_API_KEY variable is empty.
• Solution: Ensure you have a .env file in the root directory. If running via Docker, ensure you are passing the environment variable using the -e flag or an env_file.

"API request failed: Unauthorized (401)"

• Cause: The UNIFI_API_KEY provided is invalid or has been revoked in the UniFi Site Manager.
• Solution: Regenerate your API key in the UniFi Network application and update your .env file. Restart the server after making changes.

"API request failed: Not Found (404)"

• Cause: The UNIFI_API_URL is incorrect or pointing to the wrong endpoint.
• Solution: Verify your URL matches the format: https://<your-host>/proxy/network/integration/v1. Ensure there are no trailing slashes unless required by your specific proxy setup.

Connection Refused / Timeout

• Cause: The server cannot reach the UniFi host due to firewall settings or incorrect DNS.
• Solution:
  • Ensure the machine running the dashboard has outbound HTTPS access to your UniFi host.
  • If using a self-hosted controller, verify that the API port is open and accessible.

Docker-Specific Issues

Container Status: Unhealthy

The Docker image includes a built-in health check that monitors the BFF (Backend for Frontend) status.

• Cause: The Node.js server crashed or failed to start because of missing credentials.
• Solution: Check the container logs using docker logs <container_id>. If the logs show "ERROR: UNIFI_API_KEY environment variable is required," the health check will fail until the configuration is fixed.

Changes to .env not reflecting in Docker

• Cause: Docker Compose or docker run does not automatically reload environment variables from a file once a container is created.
• Solution: Recreate the container using docker-compose up -d --force-recreate or stop and remove the container before starting it again.

UI and Browser Issues

Sound notifications are not playing

• Cause: Most modern browsers block "Autoplay" audio until the user interacts with the page.
• Solution: Click anywhere on the dashboard after it loads. This "unlocks" the audio context, allowing connection alerts to play. Also, ensure the Mute Toggle (🔔 icon) in the header is not set to muted.

Data is not refreshing

• Cause: The "Auto-refresh" toggle might be disabled, or the background timer has stalled due to a lost network connection.
• Solution:
  • Check if the Auto-refresh (15s) checkbox is checked.
  • Check the browser console (F12) for any persistent 500 errors coming from the /api endpoints.

CORS Errors in Browser

• Note: The application uses a BFF (Backend for Frontend) proxy specifically to avoid CORS issues.
• Solution: Ensure you are accessing the dashboard through the Node.js server URL (e.g., http://localhost:3000) and NOT opening the index.html file directly in your browser as a local file.

Site Visibility Issues

"No sites found" / Empty Dashboard

• Cause: The API key used does not have permissions to view any sites, or the sites are currently hidden by filters.
• Solution:
  • Check the Site Filter panel to ensure sites are checked.
  • Verify that the user account associated with the API key has at least "View Only" permissions for the intended sites in the UniFi controller.