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

Auth-less SMTP:

• leave both Username and Password blank
• set an accepted From Email address
• confirm the saved config appears in the event row selector

Webhook:

• provider Test validates transport only
• real delivery also requires that provider on the target Event Matrix row
• do not use legacy provider-level notify_* fields

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

For long windows, use the built-in rolling presets. Last 7 Days, Last 30 Days, and Last 12 Months use target-local time and optimized rollups.

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. host sees the UPS device
2. /dev/bus/usb exists inside the container
3. startup logs include USB runtime access configured for device group GID ...
4. no other service holds exclusive access to the UPS

Fix path:

• use the base Compose USB mapping; do not add privileged mode or host /dev
• if automatic group detection fails, set NUTIFY_USB_GID to the numeric group owning the host USB node and recreate the container
• never use GID 0; assign the UPS to a dedicated host udev group with mode 0660 when its node is owned by root:root
• use the optional hardware override only for a stable serial/non-USB path
• use host NUT + Network Client mode when Docker cannot expose Linux USB devices
• 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:

• use Forgot Password and prove access with the persistent runtime SECRET_KEY from .env
• keep auth enabled for normal operation
• for OIDC failures, open /auth/login?local=1, then verify exact issuer, callback URI, authorized groups, and username collisions using the OpenID Connect SSO Guide

15) Symptom: False Communication or Battery Events

Typical signs:

• a short query failure appears as repeated COMMBAD/COMMOK
• ONBATT or LOWBATT appears while NUT still reports OL or OL CHRG

Current Nutify debounces communication failures per target and only applies a numeric low-charge fallback while NUT explicitly reports On Battery. If false events persist, capture consecutive polling logs, raw ups.status, active target, and exact event timestamps. Do not treat battery.charge.low as current charge.

16) Symptom: TopBar Metrics Missing Behind Reverse Proxy

Quick checks:

1. proxy forwards Host, X-Forwarded-Host, and X-Forwarded-Proto
2. proxy supports WebSocket upgrade for Socket.IO
3. public origin is listed exactly in SOCKETIO_ALLOWED_ORIGINS when required

Wildcards are rejected. Nutify falls back to authenticated HTTP snapshots every five seconds while Socket.IO is unavailable.

17) Symptom: SNMPv3 Driver Not Connected

If logs contain snmp_open: Unknown host (auto), the SNMP endpoint is missing. Select snmp-ups, enter the UPS hostname/IP in UPS Host/IP, and verify ups.conf contains port = "<UPS address>". auto is only valid for local device drivers. Local NUT Server Address is not the UPS address.

Check selected security level and matching fields:

• noAuthNoPriv: security name only
• authNoPriv: security name, auth protocol, auth password
• authPriv: auth fields plus privacy protocol and privacy password

Also confirm Docker uses /usr/lib/nut/snmp-ups, endpoint access is allowed, and the UPS supports the chosen protocol algorithms.

18) 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

19) 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>

20) 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