Troubleshooting

🛠️ Comprehensive Troubleshooting Guide

This guide provides technical troubleshooting procedures and solutions for common issues encountered when setting up, configuring, or operating SNMP Switch Manager and its visual components.

---

🔐 1. SNMP v3 Authentication Failures

If you are upgrading to SNMP v3 or setting up secure credentials for the first time and your switch fails to connect:

Common Causes & Diagnosis:

• Protocol Selection Mismatches:
  • Ensure the Authentication Protocol (HMAC-SHA or HMAC-MD5) and the Privacy Protocol (CBC-DES or None) match the exact settings configured on your switch.
  • Important: The privacy protocol AES is reserved for future expansion; check if your switch is set to DES.
• Password Policy Constraints:
  • Many enterprise switches require passwords for SNMP v3 authentication and privacy keys to be strictly between 8 and 31 characters. Keys shorter than 8 characters will cause silent connection drops.
  • Avoid special symbols in keys if your switch’s operating system (e.g. Cisco IOS, Dell OS9) restricts CLI arguments.
• Username/Security Group Mappings:
  • Verify that the SNMPv3 username is associated with a security group that has access permission. The group must be assigned the correct security level (noAuthNoPriv, authNoPriv, or authPriv) on the switch side.

Troubleshooting Checklist:

1. Verify SNMP v3 connectivity from a command line on the same network using snmpwalk:

   # Example command for authPriv (User: admin, Auth: SHA, Priv: DES)
   snmpwalk -v 3 -u admin -l authPriv -a SHA -A "AuthPassword" -x DES -X "PrivPassword" <Switch_IP> 1.3.6.1.2.1.1.1.0

2. If snmpwalk works, confirm the exact security settings match in the Home Assistant Connection & Name options menu.
3. Check the Home Assistant logs (Settings → System → Logs) for detailed PySNMP error handshakes.

---

⚡ 2. Active Controls Fail to Toggle (Admin State / PoE / Descriptions)

If you can read all ports and data, but toggling a port entity switch, toggling PoE power, or setting a port description fails:

• Missing Write Permissions on the Switch:
  • SNMP is divided into Read-Only and Read-Write access.
  • If using SNMP v2c, ensure the community string entered under connection overrides is a Read-Write (RW) community, not a Read-Only (RO) community.
  • If using SNMP v3, ensure the user belongs to an SNMP group that has write access mapping for the target OIDs (1.3.6.1.2.1.2.2.1.7 for admin status, 1.3.6.1.2.1.105.1.1.1.3 for PoE admin state, and 1.3.6.1.2.1.31.1.1.1.18 for ifAlias).
• Switch Firmware Limitations:
  • Some prosumer switches (e.g. some TP-Link, Netgear, or D-Link smart-managed lines) do not support SNMP SET operations for administrative states or descriptions via their firmware, even with a Read-Write credential. Check your manufacturer's documentation.

---

🚀 3. GitHub PR Device Flow & OID Submission Errors

If you are trying to submit a custom OID override, virtual token, or vendor filter to the community database and the PR submission fails:

• Authorization Pending Timeout:
  • Once the integration displays the 8-character OAuth code, you must complete the authorization at github.com/login/device before clicking Submit in Home Assistant. The code expires after a few minutes.
• Network Connectivity:
  • Your Home Assistant host must have external access to the GitHub API (api.github.com).
• Authentication / Fork Limits:
  • If your GitHub account has restrictions (such as a flagged account or organization policies preventing personal forks), the fork API will return an HTTP error. Check Home Assistant logs for: Failed to fork repo: HTTP 403 / 401
  • Ensure the GitHub account you log into has standard permissions to create public forks and Pull Requests.

---

📶 4. High CPU / Network Load and Bandwidth Bloat

Enabling real-time tracking for every port can put significant load on your switch and Home Assistant server:

• Bandwidth Entity Bloat:
  • Running Bandwidth Sensors in Sensors Mode on a 48-port switch creates 192 entities. Home Assistant has to query, record, and write these 192 metrics to its SQL database.
  • Solution: Go to Bandwidth Sensors → Include Rules and set include rules (e.g. matching Uplink, Server, or Router) to only generate bandwidth sensors for critical ports, excluding the rest.
• Switch CPU Spikes (SNMP Polling Overhead):
  • Frequent polling (such as 5s or 10s intervals) can cause older switches' CPU load to spike, which might lead to delayed responses or dropped packets.
  • Solution: Increase the polling interval (e.g. setting bandwidth poll to 30s or 60s, and environmental poll to 300s). You can do this dynamically from the Bandwidth and Environmental submenus in options.

---

❓ 5. Sensors or Attributes Show Unknown

If a specific health metric (CPU, memory, fan speed, or PSU status) displays Unknown or does not appear:

• Switch Model Limitation:
  • This is expected behavior. If your switch does not support or expose that specific metric in its SNMP table, the integration will output Unknown or omit it.
• Incorrect Feature OID Overrides:
  • If you applied a custom OID override for a feature but entered a wrong OID or selected an incorrect method (e.g. selecting GET when the OID is part of a table that requires WALK), the entity will fall back to Unknown.
  • Solution: Verify the OID output using a CLI tool like snmpwalk or snmpget. Double-check the OID in the Feature OID Overrides options menu and ensure you checked the attestation checkboxes correctly.

---

🖧 6. Ports Are Missing from the Dashboard or Grid

If one or more physical ports do not show up as entities or tiles on the Lovelace card:

• Interface Classification Filtering:
  • The integration automatically classifies ports. By default, it skips ports classified as virtual or unknown (e.g. VLAN interfaces, loopbacks, internal links) to keep your grid tidy.
  • If a physical port is misclassified, go to Manage Interfaces → Included Interfaces and add a custom match rule (e.g. matching Gi or Te in the port description) to force its inclusion.
• Built-in Filter Rule Conflicts:
  • A built-in vendor filter rule might be overly aggressive for your specific switch model.
  • Solution: Go to Manage Interfaces → Built-in Vendor Filters and uncheck the rule IDs for your vendor to disable them.

---

🖧 7. Device Offline or Unreachable (Unavailable Entities / Offline Notifications)

If your switch becomes unreachable due to network issues, power failure, or bad credentials:

• Initial Setup Failure: If the switch is unreachable during Home Assistant startup, the integration will fail to load and display a "Setup failed: will retry" status. Home Assistant automatically retries setup in the background. Once the network connection is restored, the integration will load fully.
• Entities Show as Unavailable: If the switch goes offline at runtime, all its switch ports and sensor entities will transition to "Unavailable" (grayed out) to prevent stale dashboard readings. They will automatically restore when the device is reachable again.
• Unreachable Persistent Notifications: The integration automatically creates a persistent notification in your Home Assistant notification drawer with a detailed error description and a "Switch Offline" graphic. This is self-healing: once the connection is restored, the notification is automatically dismissed.
• Reauthentication Required: If you modify the SNMP credentials (e.g. SNMPv3 user password or v2c community string) on the switch, the integration will detect this as an authentication error and trigger a reauth flow. A notification banner will appear on the integration page saying "Reauthentication required", allowing you to update credentials without deleting the device configuration.

---

🆘 Still Having Issues?

If your problem persists:

1. Enable Debug Logging: Add this to your configuration.yaml and restart Home Assistant to capture deep protocol logs:

   logger:
     default: warning
     logs:
       custom_components.snmp_switch_manager: debug
       pysnmp: debug

2. Collect an SNMPWalk: If requesting support for a new switch model, run an snmpwalk dump of your device's MIBs and save it to a .txt file.
3. Open a GitHub Issue: Visit the Issues Tracker and submit your logs, switch model, firmware version, and the snmpwalk dump.