Appendix B: FAQ & Troubleshooting
Overview
This appendix summarises common issues that may be encountered by various roles during platform usage, along with corresponding troubleshooting methods. It covers core modules such as login, device management, dashboards, rule chains, and alarms, helping administrators and users quickly locate and resolve problems.
I. Login & Account Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Login prompt "Incorrect username or password" | Incorrect username or password entered | 1. Confirm the username (email format) is entered correctly. 2. Click "Forgot password" to reset (if enabled). 3. Contact the Tenant Administrator to verify account status. | All roles |
| Blank page or continuous loading after login | Browser compatibility or cache issues | 1. Clear browser cache and cookies. 2. Try using the latest version of Chrome/Edge. 3. Check whether the network connection is normal. | All roles |
| Account locked | Multiple login failures triggered security policy | 1. Wait for the lockout period to expire (usually 15–30 minutes). 2. Contact the Tenant Administrator to manually unlock. | All roles |
II. Device Management Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Device status shows "Offline" | Device is not reporting telemetry data or network is disconnected | 1. Confirm the device is powered on and connected to the network. 2. Check whether the device credentials (access token) are correctly configured. 3. Check the timestamp of the most recent telemetry data reported by the device. 4. Verify whether the firewall is blocking MQTT/HTTP ports. | Tenant Administrator |
| Cannot create a new device | Device name already exists or tenant quota has been reached | 1. Check whether the device name duplicates an existing device. 2. Contact the System Administrator to confirm the tenant device quota. 3. Delete unused old devices and retry. | Tenant Administrator |
| Device credentials lost or forgotten | Access token not properly saved | 1. Click "Manage Credentials" on the device details page. 2. Click the orange pencil icon to generate a new credential (the old credential will become invalid). 3. Save the new credential securely and reconfigure it on the device side. | Tenant Administrator |
III. Dashboard Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Widget shows "No data" | Data source not configured, device not reporting data, or data key mismatch | 1. Confirm the widget data source has correctly selected a device or entity. 2. Check whether the device has reported the corresponding telemetry data (view latest telemetry on the device details page). 3. Confirm the data key name exactly matches the telemetry key (case‑sensitive). 4. Check whether the time range covers the data report time. | Tenant Administrator |
| Published dashboard cannot be viewed | Sharing not configured correctly or user lacks permissions | 1. Confirm the dashboard has been published (status is "Published"). 2. Check whether the target user has been added to the dashboard sharing settings. 3. Confirm the user is logged in and the account status is normal. 4. Confirm the user's tenant matches the tenant of the dashboard. | Tenant Administrator |
| Changes not applied after editing a dashboard | "Save" button not clicked | 1. You must click the "Save" button at the top after editing. 2. Changes made in draft state are not retained automatically. 3. If changes still do not take effect after saving, check the browser cache. | Tenant Administrator |
| End‑User cannot see an assigned dashboard | Dashboard not shared or sharing configuration is incorrect | 1. Confirm the dashboard has been published (draft status cannot be shared). 2. Check whether the user has been added to the sharing settings. 3. Confirm the user's role is "End‑User" rather than "Tenant Administrator". 4. Have the user log out and log in again to refresh permissions. | Tenant Administrator |
IV. Rule Chain Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Rule chain does not take effect | Rule chain is not correctly associated with a device or asset | 1. Confirm the rule chain has been saved and published (not in draft state). 2. Check the rule chain association configuration of the device/asset. 3. Confirm nodes in the rule chain are correctly configured (e.g., filter conditions, node connections). 4. Check the message logs in debug mode to locate the issue. | Tenant Administrator |
| Custom rule chain deleted by mistake | Operational error | 1. If a backup was previously exported, it can be imported to restore. 2. If no backup exists, it must be re‑created based on business logic. 3. It is recommended to regularly export important rule chains as backups. | Tenant Administrator |
| Rule chain import fails | JSON format error or version incompatibility | 1. Check whether the JSON file format is complete and correct (use a JSON validation tool). 2. Confirm the source platform version of the imported file is compatible with the current version. 3. Check whether entity IDs in the file conflict with those in the current environment. | Tenant Administrator |
V. Alarm Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Alarm not triggered | Alarm rule misconfigured or data does not meet conditions | 1. Check whether the condition expression in the alarm rule is correct. 2. Confirm the alarm scope (device/asset) has been correctly selected. 3. Verify whether the alarm rule is enabled (status is "Enabled"). 4. Check whether the device telemetry data meets the alarm threshold. | Tenant Administrator |
| Alarm storm (large number of duplicate alarms) | Alarm rule trigger conditions are too sensitive or data fluctuates frequently | 1. Adjust the threshold or trigger conditions in the alarm rule. 2. Configure alarm debounce parameters. 3. Check whether the device data reporting frequency is abnormal. | Tenant Administrator |
| Cleared alarm reappears | Device remains in an abnormal state | 1. Clearing an alarm only marks its status as "Cleared" and does not change the actual state of the device. 2. Check whether the device is still reporting anomalous data. 3. Identify and fix the root cause of the device fault. | Tenant Administrator |
VI. User & Permission Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Newly created user cannot log in | Password not set or not shared with the user | 1. A temporary password is generated when the user is created; the Tenant Administrator must retrieve it and inform the user. 2. On the user details page, click the orange pencil icon to reset the password. 3. Confirm the user account status is "Activated". | Tenant Administrator |
| End‑User can see data from other tenants | Sharing configuration or data source configuration is incorrect | 1. Confirm the user's tenant assignment is correct. 2. Check whether the dashboard sharing scope is limited to the current tenant. 3. Confirm the data source selects devices/assets under the current tenant. | Tenant Administrator |
VII. General Issues
| Issue | Possible Cause | Troubleshooting Steps | Applicable Role |
|---|---|---|---|
| Platform responds slowly | Large data volume or network latency | 1. Open the browser network panel (F12) to check request timings. 2. Narrow the dashboard time range to reduce data loading. 3. Clean up unnecessary old devices and historical data. 4. Contact the System Administrator to check server resource usage. | All roles |
| Page displays abnormally or elements are misaligned | Browser zoom or resolution issue | 1. Reset browser zoom to 100%. 2. Use a 1920×1080 or higher resolution monitor. 3. Try using incognito mode to rule out extension interference. | All roles |