Skip to content

Troubleshooting

Jump to bottom
MrD3y5eL edited this page Oct 23, 2024 · 2 revisions

Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Home Assistant Unraid integration.

🔍 Common Issues and Solutions

Installation Issues

Integration Not Found in HACS

Problem: Unable to find the Unraid integration in HACS. Solutions:

  1. Ensure HACS is properly installed
  2. Try refreshing HACS by going to HACS → ⋮ → Clear cache
  3. Add custom repository:
    • HACS → ⋮ → Custom repositories
    • Add URL: https://github.com/domalab/ha-unraid
    • Category: Integration

Installation Fails

Problem: Integration fails to install through HACS. Solutions:

  1. Clear Home Assistant browser cache
  2. Remove integration if previously installed: 
    rm -rf /config/custom_components/unraid
  3. Restart Home Assistant
  4. Try installation again

Connection Issues

Cannot Connect to Unraid Server

Problem: Integration fails to connect during setup. Solutions:

  1. Verify SSH credentials: 
    ssh username@unraid-ip
  2. Check SSH port (default 22)
  3. Ensure Unraid server is reachable: 
    ping unraid-ip
  4. Verify no firewall rules blocking access

Connection Drops Frequently

Problem: Integration loses connection to Unraid server. Solutions:

  1. Check network stability
  2. Adjust update interval in configuration
  3. Verify SSH service is running on Unraid: 
    # On Unraid server
ps aux | grep sshd
  4. Check Home Assistant logs for timeout errors

Sensor Issues

Sensors Show 'Unavailable'

Problem: Sensors display as unavailable in Home Assistant. Solutions:

  1. Verify entity permissions
  2. Check sensor update interval
  3. Validate sensor paths on Unraid system
  4. Restart Home Assistant

Incorrect Sensor Values

Problem: Sensors show wrong or unexpected values. Solutions:

  1. Compare with Unraid dashboard
  2. Check sensor attributes in Developer Tools
  3. Verify command outputs directly on Unraid
  4. Clear sensor cache if available

Docker Control Issues

Cannot Control Docker Containers

Problem: Unable to start/stop Docker containers. Solutions:

  1. Verify Docker service is running: 
    # On Unraid server
docker ps
  2. Check user permissions for Docker commands
  3. Ensure container names match exactly
  4. Test Docker commands directly on Unraid

Container Status Not Updating

Problem: Container states don't refresh properly. Solutions:

  1. Force update through service call: 
    service: unraid.force_update
data:
   entry_id: YOUR_UNRAID_IP
  2. Adjust update interval
  3. Check for Docker service issues

VM Control Issues

Cannot Control VMs

Problem: Unable to start/stop virtual machines. Solutions:

  1. Verify libvirt is running: 
    # On Unraid server
ps aux | grep libvirt
  2. Check VM names match exactly
  3. Test VM controls directly on Unraid
  4. Verify user permissions for VM operations

Service Command Issues

Commands Fail to Execute

Problem: Service commands don't work. Solutions:

  1. Test command directly on Unraid
  2. Check command syntax
  3. Verify user permissions
  4. Look for command output in Home Assistant logs

Script Execution Fails

Problem: User scripts won't run. Solutions:

  1. Check script permissions: 
    ls -l /boot/config/plugins/user.scripts/scripts
  2. Verify script exists in correct location
  3. Test script manually on Unraid
  4. Check script syntax

🔍 Diagnostic Steps

1. Check Home Assistant Logs

# Look for errors
grep -i "unraid" /config/home-assistant.log

2. Verify Integration Status

  1. Go to Settings → Devices & Services
  2. Find Unraid integration
  3. Check for error messages
  4. Try removing and readding if needed

3. Test Basic Connectivity

# From Home Assistant
ping UNRAID_IP

# Test SSH
ssh USERNAME@UNRAID_IP

# Test Docker
docker ps

4. Validate Permissions

  1. Check SSH user permissions
  2. Verify Docker group membership
  3. Test file access permissions
  4. Validate script execution rights

🛠️ Advanced Troubleshooting

Debug Logging

Enable debug logging by adding to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.unraid: debug

Service Command Testing

Test service commands using Developer Tools:

service: unraid.execute_command
data:
  entry_id: "UNRAID_IP"
  command: "echo 'test'"

Network Analysis

  1. Check for network issues: 
    traceroute UNRAID_IP
  2. Verify no firewall blocks
  3. Test alternate ports if needed
  4. Check for VPN interference

📋 Reporting Issues

If you cannot resolve an issue:

  1. Collect Information:

    • Home Assistant logs
    • Integration configuration
    • Error messages
    • Steps to reproduce

  2. Check Existing Issues:

  3. Create New Issue:

    • Use the issue template
    • Include all collected information
    • Describe your setup
    • List steps tried

🔄 Recovery Steps

Integration Reset

  1. Remove integration
  2. Clear cache: 
    rm -rf /config/custom_components/unraid
  3. Restart Home Assistant
  4. Reinstall integration

Configuration Backup

Always backup before major changes:

  1. Backup Home Assistant configuration
  2. Note down integration settings
  3. Document custom automations
  4. Save any modified scripts

📞 Getting Help

  1. Community Support:

    • Home Assistant Community Forums
    • GitHub Discussions

  2. Documentation:

Remember to always test commands and scripts directly on your Unraid server before implementing them in Home Assistant automations.

Clone this wiki locally