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 pointing to a deleted macro; AV sources whose backing device was removed; UI controls bound to deleted zones; macro schedules pointing at missing macros
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+; 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
  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

The summary header shows the total checks run, how many surfaced issues, and per-severity counts (errors, warnings, info).

Filtering and triage​

  • Search — full-text filter across issue titles, descriptions, and item labels. 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 (label, details, and an Open › button that jumps to the matching admin page with the row pre-filtered)

Click the card header (or the Show / Hide items toggle) to collapse the 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.

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 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.