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
.envfile is missing, renamed incorrectly, or theUNIFI_API_KEYvariable is empty. - Solution: Ensure you have a
.envfile in the root directory. If running via Docker, ensure you are passing the environment variable using the-eflag or anenv_file.
"API request failed: Unauthorized (401)"
- Cause: The
UNIFI_API_KEYprovided is invalid or has been revoked in the UniFi Site Manager. - Solution: Regenerate your API key in the UniFi Network application and update your
.envfile. Restart the server after making changes.
"API request failed: Not Found (404)"
- Cause: The
UNIFI_API_URLis 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 rundoes not automatically reload environment variables from a file once a container is created. - Solution: Recreate the container using
docker-compose up -d --force-recreateor 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
500errors coming from the/apiendpoints.
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 theindex.htmlfile 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.