Unifi Cloud | Troubleshooting HTTP 500 Errors in the Unifi Cloud Child Inspector

Overview ✨

An HTTP 500 error means the server could not complete the requested operation. In the UniFi Cloud Child Inspector, this may occur while authenticating, connecting to a UniFi console, loading site information, or retrieving device and client data.

The issue may be temporary or limited to a specific console, site, account, or data request. If the error persists, use the troubleshooting steps below to identify the affected resource and provide the relevant error details when contacting Liongard Support.

⚠️ This article provides troubleshooting steps for HTTP 500 errors reported by the UniFi Cloud Child Inspector. When sharing diagnostic information with Liongard Support, remove passwords, API keys, access tokens, and other sensitive information from logs or screenshots.

Common Error Messages

HTTP 500 Internal Server Error
Unable to retrieve UniFi Cloud data
The child inspector returned an unexpected response
Request failed while loading the UniFi console
Unable to load sites, devices, clients, or statistics
Connection to the UniFi Cloud service failed

Why Does This Happen?

HTTP 500 errors can occur when a request cannot be completed between Liongard and the UniFi environment. Common causes include:

Temporary service or network interruption: The UniFi Cloud service, console, or network connection may be temporarily unavailable.
Console connectivity issues: The console may be offline, restarting, unreachable, or unable to communicate with the cloud service.
Authentication or authorization issues: A session, token, account permission, or console association may no longer be valid.
Unsupported or outdated software: The UniFi console or Network application may be running a version with compatibility issues.
Request-specific data issues: A particular site, device, client, or statistics request may return incomplete or unexpected data.
Intermittent upstream failures: A request may fail temporarily even when the console appears to be operating normally.

Steps to Resolve

1. Confirm the Failure Scope

Wait a few minutes, then run the affected Inspector again.
Check whether the same HTTP 500 error occurs.
Confirm which UniFi console and site are associated with the affected Inspector.
If available, run another UniFi Cloud Child Inspector and compare the results.

📝 If the error occurs only with one Inspector, the issue may be specific to its associated console or site. If multiple Inspectors are affected, the issue may be related to authentication, connectivity, or a broader service condition.

2. Check the UniFi Console

Sign in to the UniFi management interface.
Confirm that the associated console is online and accessible.
Confirm that the affected site is available and loads normally.
Check the UniFi Network application for any errors, warnings, or degraded status.
If the console or application is restarting or updating, allow the process to complete before running the Inspector again.

⚠️ Do not repeatedly restart the console. Allow any active restart, update, or recovery process to complete before retrying the Inspector.

3. Verify the Integration Access

Verify that the required permissions are still assigned.
Check for recent changes to the permissions, console association, or authorization.
If the API key is no longer valid, recreate the API key.
Run the affected Inspector again after API key is restored.

4. Check UniFi Software Versions

Check the UniFi OS and UniFi Network application versions on the affected console.
Check whether the console or Network application was recently upgraded, downgraded, or migrated.
Confirm that the installed versions are supported.
If an update is required, follow your organization's normal change process.
Allow the console and Network application to fully start before running the Inspector again.

ℹ️ Do not assume that the newest version is always the correct immediate fix. Confirm compatibility and follow the organization’s change-control process before upgrading production systems.

5. Determine What the Inspector Cannot Retrieve

Check which part of the inspection is failing:

Inspector behavior	What to check
Inspector fails to connect	Confirm API Key, console access, and connectivity.
Sites cannot be retrieved	Confirm the API Key has can access the affected sites.
Devices or clients cannot be retrieved	Confirm the site and UniFi Network application are operating normally.
Statistics or historical data fails	Check whether current device and client data is available while historical data fails.
Only one Inspector fails	Compare the affected Inspector with another Inspector using a different site or console, if available.

6. Test the UniFi API Outside of Liongard - Important ‼️

If the Inspector continues to return an HTTP 500 error, reproduce the same UniFi API request outside of Liongard. This helps determine whether the error is being returned by the UniFi API or occurs only when Liongard processes the response.

Identify the API Request

First, identify the API request associated with the failed Inspector operation. The endpoint will vary depending on what the Inspector is attempting to retrieve. For example, a request for device information may use the Devices endpoint, while another inspection operation may use a different endpoint.

Use the same API endpoint, HTTP method, site/console identifiers, and query parameters shown in the failing request.

For example, a Devices request may look like:

curl -i -X GET \
  "https://api.ui.com/v1/connector/consoles/<CONSOLE_ID>/proxy/network/integration/v1/sites/<SITE_UUID>/devices?limit=5&offset=0" \
  -H "X-API-KEY: <API_KEY>" \
  -H "Accept: application/json"

Replace the values as follows:

<CONSOLE_ID> — Replace with the UniFi Console ID associated with the affected Inspector.
<SITE_UUID> — Replace with the UUID of the affected UniFi site.
<API_KEY> — Replace with the UniFi Site Manager API key used for the integration.

If the failing Inspector request uses a different endpoint, keep the same structure but replace the portion after /proxy/ with the endpoint that corresponds to the failed operation.

For example, if the failing request is for another resource, do not use /devices simply because it is shown in the example above. The test should reproduce the endpoint that is actually returning the HTTP 500 error.

Run the Request

Open a command-line tool such as Terminal, PowerShell, or Command Prompt on a system that can make outbound HTTPS requests.
Copy the cURL request and replace the placeholders with the values from the affected UniFi environment.
If required, modify the endpoint and query parameters so the request matches the failed Inspector operation.
Run the request.
Record the HTTP status code, response body, and any Ubiquiti Request ID or correlation ID returned by the API.
Compare the API response with the HTTP 500 error reported by the Liongard Inspector.

Interpret the Result

The same HTTP 500 error is returned by the UniFi API:
The failure can be reproduced outside of Liongard. This indicates that the API request itself is returning an error and should be investigated within the UniFi environment or with Ubiquiti Support.
The API request succeeds outside of Liongard:
The UniFi API is successfully returning data for the request. If the Liongard Inspector continues to return an HTTP 500 error, provide the successful API response and the Inspector error details to Liongard Support for further investigation.
A different error is returned:
Provide the HTTP status code and response returned by UniFi to help determine whether the issue is related to authentication, permissions, the requested resource, or the API request itself.

When to Contact Liongard Support 🦁

Contact Liongard Support if:

The Inspector continues to fail after the recommended troubleshooting steps.
The UniFi API request succeeds outside of Liongard, but the Inspector continues to return an HTTP 500 error.
The issue affects multiple Inspectors and cannot be explained by a UniFi console or site issue.
You have confirmed that the UniFi console, site access, authorization, and supported software versions are functioning normally.

Information to Provide Liongard Support

When contacting Liongard Support, provide the following information from the affected UniFi environment:

Inspector details: Inspector name, UniFi Console, and affected site.
cURL/API request: Screenshot of the API request used to reproduce the issue outside of Liongard, including the endpoint, HTTP method, and request parameters or body where applicable.
API response: Screenshot showing the HTTP status code and complete response returned by UniFi.
Request/Correlation ID: Ubiquiti Request ID or correlation ID, if provided.
Failure time: Approximate date, time, and timezone of the failed request.
UniFi console status: Screenshot showing the affected console and site status.
Affected data: If applicable, screenshots showing the affected devices, clients, or other records related to the failed request.
Relevant logs: UniFi/console logs covering the failure timeframe, if available.