Troubleshooting Guide

Troubleshooting Guide (By Symptom)

This guide helps you diagnose Nutify issues quickly using symptom-based checks. It is designed for operators who need fast recovery steps.

1) How to Use This Guide

Use this sequence every time:

1. identify the visible symptom
2. run quick checks in order
3. apply the smallest safe fix
4. validate on UI and target behavior

2) 5-Minute Rapid Triage

Before deep debugging, check these five points:

1. Nutify service/container is running.
2. Login works and dashboard opens.
3. Active target in TopBar is the one you are testing.
4. System -> Advanced -> NUT Manager shows expected target inventory.
5. System -> Log shows no critical recurring errors.

3) Symptom: Web UI Does Not Open

Typical signs:

• browser cannot load http://<host>:5050
• timeout/connection refused

Quick checks:

1. confirm container/process is running
2. confirm port 5050 is exposed and free
3. inspect runtime logs

Fix path:

• restart stack/process
• resolve port conflicts
• verify compose path and active compose file are the expected one

4) Symptom: Wizard Does Not Continue

Typical signs:

• Next button does not move forward
• validation blocks save/test

Quick checks:

1. all required fields are filled
2. selected topology matches selected connection details
3. target test passes before save
4. display name vs UPS identifier are not confused

Fix path:

• correct missing/incompatible fields
• retest target
• proceed only when validation is green

5) Symptom: Save & Reboot Fails at Wizard End

Typical signs:

• configuration save error
• restart step fails

Quick checks:

1. open logs and find the first backend error message
2. verify NUT config values generated by wizard are valid
3. verify no invalid value type was submitted in critical fields

Fix path:

• fix the first error shown in logs (not downstream errors)
• rerun test + save sequence
• rerun restart only after clean validation

6) Symptom: Target Appears Offline in Multi Profile

Typical signs:

• target card shows disconnected/offline
• data not refreshing for one target

Quick checks:

1. verify host, port, UPS identifier (ups@host logic)
2. verify monitor username/password
3. verify remote NUT server health
4. verify network/firewall path
5. run poll now from NUT Manager

Fix path:

• correct connection details
• re-enable target if disabled
• retest connectivity and check topbar switching

7) Symptom: Target Switch Works But Data Looks Wrong

Typical signs:

• topbar target changes but charts look unchanged
• timezone or currency appears inconsistent

Quick checks:

1. confirm active target in TopBar before opening page
2. confirm target-specific PowerFlow settings are correct
3. refresh page after target switch to confirm data context

Fix path:

• correct target-specific settings in PowerFlow
• verify you are not reading cached expectations from previous target

8) Symptom: Timezone/Currency Not Matching Expectations

Typical signs:

• displayed times look shifted
• costs look in wrong currency context

Quick checks:

1. open target-scoped PowerFlow for active target
2. verify target timezone and currency values
3. switch to another target and compare values to confirm per-target scope

Fix path:

• set correct values per target in PowerFlow
• validate by reloading a chart page and checking labels/tooltips

9) Symptom: Notifications Are Not Delivered

Typical signs:

• event happens but no mail/ntfy/telegram/webhook message

Quick checks:

1. Provider channel exists and is enabled in System -> Provider
2. provider test action succeeds
3. provider is attached to target in Settings -> Notify
4. target scope is correct (you are editing the right active target)

Fix path:

• repair provider credentials or endpoint
• reattach provider in target Notify config
• trigger a test event and recheck delivery

10) Symptom: Reports Are Not Delivered or Missing

Typical signs:

• report scheduler seems active but no report arrives
• on-demand report fails

Quick checks:

1. provider channel for report delivery is valid
2. reporter config is saved for correct target
3. schedule window/time settings are valid
4. logs show no report generation exception

Fix path:

• fix channel config first
• rerun on-demand report once
• then validate scheduled delivery on next run

11) Symptom: Sidebar or TopBar Actions Do Not React

Typical signs:

• click appears ignored
• navigation only changes after manual refresh

Quick checks:

1. verify current page URL and active route
2. hard refresh browser once
3. check browser console for runtime JS errors
4. test in second browser to rule out extension/cache effects

Fix path:

• clear browser cache and retry
• restart frontend/backend process if runtime asset mismatch is suspected

12) Symptom: NUT Manager Changes Do Not Appear in Dashboard

Typical signs:

• target saved in manager but not visible/switchable in UI

Quick checks:

1. target is enabled
2. target has valid connection details
3. one target is marked primary/default as expected
4. reload dashboard after save

Fix path:

• enable target and validate connection
• verify manager save succeeded
• reopen dashboard and confirm topbar inventory

13) Symptom: Local USB UPS Not Detected in Container

Typical signs:

• auto-detect finds no device
• local target test fails with device access issues

Quick checks:

1. compose includes USB/device mounts and privileges
2. host sees UPS USB device
3. no other service holds exclusive access to UPS

Fix path:

• restore correct compose hardware mappings
• stop conflicting UPS service on host if needed
• retry auto-detect and then manual fallback if needed

14) Symptom: Login Problems

Typical signs:

• auth denied despite expected credentials

Quick checks:

1. confirm username/password correctness
2. verify auth bypass flags are not unintentionally set
3. confirm you are opening the correct instance

Fix path:

• reset credentials via admin workflow when available
• keep auth enabled for normal operation

15) Logs: What to Capture Before Asking for Help

Always capture:

1. exact symptom and timestamp
2. active target and scenario (single/multi)
3. one screenshot of UI state
4. relevant log excerpt (first real error, not only follow-up noise)
5. recent change done before failure

16) Escalation Template (Copy/Paste)

Use this template when opening an issue:

Environment: Docker + image tag/version
Profile: Single/Multi
Topology: <selected topology>
Symptom: <what is failing>
Expected: <what should happen>
When started: <date/time>
Recent changes: <what changed before issue>
TopBar active target: <target name>
Logs (first error): <paste>
Tried already: <checks/fixes performed>

17) Prevention Checklist

• keep provider catalog clean and tested
• keep target naming consistent
• verify TopBar target before any save
• backup DB/config before major changes
• validate one change at a time