Common Issues & Resolutions

Agent Connectivity Issues

Agent connectivity problems are the most frequently reported issue. The typical symptom is devices or rooms showing as offline in the platform even though the physical equipment is functioning normally. This usually indicates that the agent is not communicating with the platform backend.

The first thing to check is whether the agent service is running on the host machine. Agents can stop due to system reboots, resource constraints, or service manager changes. If the service is stopped, restarting it usually resolves the issue. Next, verify that the host has network connectivity to the platform endpoint. Firewall changes, proxy updates, or DNS issues are common causes of connectivity loss.

If the agent is running and the network path is clear, check the agent logs for error messages. Common errors include authentication failures (which may indicate an expired or rotated API key), certificate issues, or version incompatibilities. Updating the agent to the latest version resolves many of these issues. Document the root cause in the ticket so the team can track recurring patterns.

Dashboard Loading Problems

Customers sometimes report that their dashboard is slow to load, displays incomplete data, or shows errors on certain widgets. These issues can stem from browser-side problems, data loading issues, or platform performance.

Start by asking the customer to try a hard refresh of the page and clear their browser cache. Many dashboard rendering issues are caused by stale cached assets after a platform update. If the problem persists, ask the customer to try a different browser or an incognito window to rule out browser extensions or settings.

If the issue is not browser-related, investigate whether the affected widgets are trying to load a large amount of data. Dashboards that span very large time ranges or include many rooms may take longer to render. Suggest narrowing the time range or filtering to a specific building. If the issue is widespread and not specific to one user, it may indicate a platform-side performance problem that should be escalated.

Alert Configuration Errors

Customers may report that alerts are not firing when expected, firing too frequently, or not being delivered to the correct recipients. These issues are almost always related to the configuration of alert rules or notification settings.

For alerts not firing, check that the alert rule is active and that its conditions match what the customer expects. A common mistake is setting a threshold that is too high or too low relative to normal device behavior. Verify that the rule applies to the correct scope of rooms or devices.

For noisy alerts, review the rule's threshold and frequency settings. An alert that triggers on every brief connectivity blip will generate excessive notifications. Suggest adding a delay or debounce period so the alert only fires if the condition persists for a specified duration. For delivery issues, verify the customer's notification settings and check that email addresses are correct and that messages are not being caught by spam filters.

User Access Issues

Access issues include login failures, permission errors, and users being unable to see the data they expect. These are usually straightforward to diagnose and resolve once you understand the user management model.

For login failures, first confirm whether the customer is using local credentials or SSO. For local credentials, check that the account exists, is active, and has not been locked due to too many failed attempts. For SSO, the issue is typically on the identity provider side, such as a misconfigured claim, an expired SAML certificate, or the user not being assigned to the application in the identity provider.

Permission errors occur when a user has an account but cannot access certain features or data. Check their assigned role and namespace or tenant scope. A user assigned to the wrong tenant will not see any rooms, and a user with a Viewer role will not be able to acknowledge alerts. Adjust the role or scope as needed and confirm with the customer that they can now access what they need.

Performance Concerns

Occasionally, customers report that the platform feels slow or unresponsive. Performance concerns can be subjective, so start by understanding specifically what feels slow: page load times, data refresh rates, search results, or report generation.

For page load issues, check whether the problem is isolated to one user or widespread. If it is one user, their network connection, browser, or device may be the bottleneck. If multiple users are affected, it may indicate a platform-side issue that requires investigation by the infrastructure or engineering team.

For data-related performance issues, such as slow-loading dashboards or reports, check whether the customer is querying a very large dataset. Large environments with thousands of devices and long time ranges can produce heavy queries. Suggest reducing the scope of the query, using filters, or breaking the report into smaller time periods. If the performance issue persists even with reasonable query sizes, escalate to the engineering team with details about the affected tenant, time range, and specific views or reports involved.