Skip to main content

Diagnostics

The Diagnostics page runs a battery of read-only health checks across the database and live system state, then surfaces orphans, duplicates, broken references, stale data, and configuration smells. It's the first place to look when something feels wrong but no error is being thrown — and the right tool for periodic hygiene sweeps before backups, upgrades, or handover.

What it checks​

Each check is a small read-only routine that returns 0..N issues. Checks never mutate state — they're safe to run anytime, including in production.

CategoryExamples
Orphan Referencesmacro steps (or a step's device/zone/macro target) pointing at a deleted record; AV sources or AV zones whose backing device or zone was removed; UI controls, page widgets, and zone mappings bound to deleted zones or widgets; schedules and attribute triggers pointing at a missing macro; sub-devices whose controller device was deleted; zones whose subsystem was removed
Duplicatestwo devices configured with the same IP; multiple zones sharing a name within a subsystem; macro names that collide
Empty / Unusedenabled macros with no enabled steps; AV zones with no sources; UI pages with no widgets; widgets defined but never placed
Naming Issuesentity names that violate the lowercase_with_underscores convention
Connectivityenabled devices reporting disconnected; enabled devices that look connected but haven't pushed any attribute update in 24h+ (activity on a device's zones counts — drivers like BACnet/Modbus report onto zone attributes rather than device attributes); dynamic attributes (state/level/temperature/etc.) that haven't changed in 48h+
Config Smellssensitive-looking attributes (password, api_key, etc.) stored in plaintext; disabled steps inside enabled macros
Securityroles with no users assigned; admin accounts inactive for 90+ days
Integrityrecursive macro execution loops (run_macro / for_each cycles) — surfaced with the actual cycle path
Performanceattribute_history table size warnings (>500K rows = moderate, >1M = large, >5M = very large)

Running the checks​

  1. Navigate to Insights → Diagnostics (Open Diagnostics)
  2. The page runs every check on load; results appear within a couple of seconds for most installs
  3. Click Re-run to refresh after fixing something

When every check passes, the card list is replaced by a green "All N checks passed. The system looks healthy." banner — a clean run is the expected result on a well-maintained system.

The summary header shows four tiles: Checks (how many checks ran) and Errors / Warnings / Info. The three severity tiles count affected items, not checks — one check that flags twelve zones adds 12 to its severity tile, so these numbers track the size of the cleanup, not the number of findings.

Filtering and triage​

  • Search — full-text filter across issue titles, descriptions, and the label and details of every affected item. Useful when you know an entity name and want to find every check that flagged it.
  • Severity filter — narrow to errors-only, warnings-only, or info-only.
  • Category filter — narrow to one category (e.g. only Orphan References).

Issues are sorted errors → warnings → info, and within severity by item count descending — so the most urgent thing to fix is always at the top.

Issue cards​

Each issue card shows:

  • Severity badge — error / warning / info
  • Title — what the check found
  • Count — how many entities are affected
  • Category — one of the categories above
  • Description — what the check is looking for
  • Fix — the recommended remediation
  • Affected items — drill-down list: each row shows a label, its details, and an Open › button that jumps straight to the relevant admin page. On the standard list screens (Devices, Zones, Macros, AV Sources, UI Pages, and the like) it opens pre-filtered to the offending row; a handful of pages you browse differently — Attributes, for example, which you open by system target — simply land you on the right screen to find it yourself.

Click the card header (or the Hide items / Show N items toggle at the foot of each card) to collapse the affected-item list when you want a higher-level view.

tip

The Open › button on each item is the fastest way to fix an issue — instead of browsing back to e.g. Macros and searching for the offender, click straight through to the row that needs attention.

When to run​

  • Before a backup — a clean diagnostics run = a clean backup. Catches dangling references that would silently bloat the snapshot.
  • After a large migration or import — verify orphan references didn't get introduced by partial imports.
  • Quarterly hygiene — admin accounts inactive for 90+ days, plaintext secrets, large attribute_history table.
  • When something feels off — silent device, missing alert, scene that does nothing. Diagnostics often surfaces the cause without needing to dig through logs.

Explain & Fix with AI​

The Explain & Fix with AI button in the header opens the AI assistant with a narrated audit: the assistant re-runs the same check battery itself (so its view is always current), walks the findings worst-first in plain language, and proposes concrete next steps. Where one of its tools can make the repair (rebinding a stale reference, correcting an attribute), it offers to do it — every change still goes through the normal confirmation gate — and for anything else it points you at the right admin page. You can also ask follow-ups ("only the security findings", "why does macro 12 keep showing up here?").

What it does NOT do​

  • No mutations. Diagnostics never deletes orphans, fixes references, or changes attributes. Each fix has to be made deliberately on the appropriate admin page — or explicitly approved through the AI assistant's confirmation prompt — so you don't lose work to a bulk auto-clean.
  • Not a replacement for monitoring. Stale-attribute and disconnected-device checks are useful for hygiene but won't page you. Use Monitoring for active alerting.
  • Not a backup audit. For verifying backup integrity, see Backup & Restore.