1

Troubleshooting

sq4ind edited this page 2025-09-28 12:46:04 +00:00

Table of Contents

• 🔧 Troubleshooting Guide
• 🚨 Common Issues
• Integration Not Found
• Cannot Connect to AdGuard Home
• No Entities Created
• Services Not Working
• 📊 Performance Issues
• Slow Response Times
• High CPU Usage
• 🔐 Authentication & Security Issues
• Authentication Failures
• SSL Certificate Issues
• 📡 Network & Connectivity Issues
• DNS Resolution Problems
• Port Conflicts
• Firewall Issues
• 🔄 Update & Upgrade Issues
• Update Failures
• Configuration Migration
• 🐛 Debugging Steps
• Enable Debug Logging
• Collect Diagnostic Information
• Test API Manually
• 📞 Getting Help
• Before Seeking Support
• Where to Get Help
• Issue Report Template
• Emergency Recovery
• Test Configuration

🔧 Troubleshooting Guide

Having issues with AdGuard Control Hub? This comprehensive guide covers common problems and their solutions.

🚨 Common Issues

Integration Not Found

Problem: AdGuard Control Hub doesn't appear in the integrations list.

Solutions:

1. HACS Users:

   # Verify repository was added correctly
   # Go to HACS > Integrations > Menu > Custom repositories
   # Check if your repository URL is listed
   

2. Manual Installation:

   # Check file location
   ls -la /config/custom_components/adguard_hub/
   
   # Should show:
   # __init__.py, manifest.json, config_flow.py, etc.
   

3. General:

   • Restart Home Assistant
   • Clear browser cache (Ctrl+F5)
   • Check Home Assistant logs for errors

Cannot Connect to AdGuard Home

Error: "Failed to connect to AdGuard Home"

Diagnostic Steps:

# Test basic connectivity
ping 192.168.1.100  # Replace with your AdGuard IP

# Test HTTP access
curl -I http://192.168.1.100:3000/

# Test with authentication
curl -u admin:password http://192.168.1.100:3000/control/status

Solutions:

1. Check IP Address and Port:

   • Verify AdGuard Home IP address
   • Confirm port (usually 3000)
   • Test from Home Assistant server directly

2. Authentication Issues:

   • Verify username/password in AdGuard Home web interface
   • Create dedicated user for Home Assistant
   • Ensure user has admin privileges

3. Network Issues:

   # Check if AdGuard Home is running
   sudo systemctl status AdGuardHome
   
   # Check listening ports
   netstat -tlnp | grep :3000
   
   # Check firewall
   sudo ufw status
   

4. SSL/TLS Issues:

   • Disable "Verify SSL" for self-signed certificates
   • Use HTTP instead of HTTPS for testing
   • Check certificate validity

No Entities Created

Problem: Integration connects but creates no entities.

Diagnostic:

# Enable debug logging in configuration.yaml
logger:
  default: warning
  logs:
    custom_components.adguard_hub: debug

Solutions:

1. Check AdGuard Home Configuration:

   • Ensure AdGuard Home has clients configured
   • Verify API endpoints are accessible
   • Check AdGuard Home logs for errors

2. Integration Issues:

   • Reload integration: Settings > Devices & Services > AdGuard Control Hub > Reload
   • Remove and re-add integration
   • Check entity registry for disabled entities

3. Permissions:

   # Check file permissions
   sudo chown -R homeassistant:homeassistant /config/custom_components/
   sudo chmod -R 755 /config/custom_components/
   

Services Not Working

Problem: Service calls fail or don't have expected effect.

Solutions:

1. Check Service Calls:

   # Test in Developer Tools > Services
   service: adguard_hub.emergency_unblock
   data:
     duration: 60
     clients: ["all"]
   

2. Verify Client Names:

   • Use exact client names as they appear in AdGuard Home
   • Check entity names in Home Assistant
   • Use Developer Tools > States to verify entity IDs

3. API Limitations:

   • Some AdGuard Home versions have API limitations
   • Check AdGuard Home version compatibility
   • Review AdGuard Home documentation

📊 Performance Issues

Slow Response Times

Symptoms: Long delays when toggling switches or calling services.

Solutions:

1. Adjust Scan Interval:

   # In configuration.yaml
   adguard_hub:
     scan_interval: 60  # Increase from default 30
   

2. Reduce Entity Count:

   # Disable unnecessary features
   adguard_hub:
     blocked_services_as_switches: false
     enable_statistics: false
   

3. Network Optimization:

   • Use wired connection instead of Wi-Fi
   • Check network latency to AdGuard Home
   • Consider AdGuard Home hardware resources

High CPU Usage

Problem: Home Assistant shows high CPU usage from the integration.

Solutions:

1. Optimize Configuration:

   adguard_hub:
     scan_interval: 120  # Reduce update frequency
     auto_create_clients: false  # Manual client management
   

2. Check Logs:

   # Look for excessive API calls or errors
   grep "adguard_hub" /config/home-assistant.log
   

3. System Resources:

   • Monitor AdGuard Home resource usage
   • Check Home Assistant system resources
   • Consider hardware upgrades

🔐 Authentication & Security Issues

Authentication Failures

Error: "Invalid username or password"

Solutions:

1. Verify Credentials:

   • Test login in AdGuard Home web interface
   • Check for special characters in password
   • Ensure caps lock and keyboard layout

2. Create Dedicated User:

   AdGuard Home Web Interface:
   Settings > General Settings > Authentication
   Add user: "homeassistant" with admin privileges
   

3. Check Account Status:

   • Ensure account isn't locked or disabled
   • Verify admin privileges
   • Check AdGuard Home user management

SSL Certificate Issues

Error: "SSL certificate verification failed"

Solutions:

1. For Self-Signed Certificates:

   • Disable "Verify SSL" in integration settings
   • Or add certificate to trusted store

2. For Invalid Certificates:

   # Check certificate validity
   openssl s_client -connect 192.168.1.100:443 -servername your-domain
   

3. Use HTTP for Testing:

   • Temporarily switch to HTTP
   • Test basic functionality
   • Re-enable HTTPS after fixing certificates

📡 Network & Connectivity Issues

DNS Resolution Problems

Problem: Home Assistant can't resolve AdGuard Home hostname.

Solutions:

1. Use IP Address:

   • Replace hostname with IP address
   • Test connectivity with IP first

2. Check DNS Configuration:

   # Test DNS resolution
   nslookup adguard.local
   dig adguard.local
   

3. Update /etc/hosts:

   # Add to /etc/hosts if needed
   echo "192.168.1.100 adguard.local" >> /etc/hosts
   

Port Conflicts

Problem: Port 3000 is not accessible or in use by another service.

Solutions:

1. Check Port Usage:

   # See what's using port 3000
   sudo lsof -i :3000
   netstat -tlnp | grep :3000
   

2. Change AdGuard Home Port:

   # In AdGuard Home configuration
   http:
     address: 0.0.0.0:3001  # Change port
   

3. Update Integration Configuration:

   • Remove and re-add integration
   • Use new port number

Firewall Issues

Problem: Connection blocked by firewall.

Solutions:

1. Check Firewall Status:

   # Ubuntu/Debian
   sudo ufw status
   
   # CentOS/RHEL
   sudo firewall-cmd --list-all
   

2. Allow AdGuard Home Port:

   # UFW
   sudo ufw allow from 192.168.1.10 to any port 3000
   
   # firewalld
   sudo firewall-cmd --add-port=3000/tcp --permanent
   sudo firewall-cmd --reload
   

3. Test Without Firewall (temporarily):

   # Disable firewall for testing (CAUTION)
   sudo ufw disable
   # Test connection, then re-enable
   sudo ufw enable
   

🔄 Update & Upgrade Issues

Update Failures

Problem: Integration fails to update via HACS.

Solutions:

1. Manual Update:

   # Remove old version
   rm -rf /config/custom_components/adguard_hub
   
   # Download and install new version
   # (Follow manual installation steps)
   

2. HACS Cache Issues:

   • Restart Home Assistant
   • Clear HACS cache
   • Re-add custom repository if needed

3. Version Conflicts:

   • Check Home Assistant version compatibility
   • Review integration changelog
   • Consider rolling back if needed

Configuration Migration

Problem: Settings lost after update.

Solutions:

1. Backup Before Updates:

   # Backup configuration
   cp -r /config/custom_components/adguard_hub /config/backup/
   

2. Reconfigure Integration:

   • Remove integration
   • Re-add with previous settings
   • Verify entity names haven't changed

🐛 Debugging Steps

Enable Debug Logging

# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.adguard_hub: debug
    custom_components.adguard_hub.api: debug
    custom_components.adguard_hub.config_flow: debug

Collect Diagnostic Information

When reporting issues, collect:

1. Home Assistant Version:

   # In Home Assistant
   Settings > System > Repairs > Three dots > System Information
   

2. Integration Version:

   # Check manifest.json
   cat /config/custom_components/adguard_hub/manifest.json | grep version
   

3. AdGuard Home Version:

   # Check in AdGuard Home web interface or API
   curl -u admin:password http://192.168.1.100:3000/control/status | grep version
   

4. Error Logs:

   # Extract relevant logs
   grep -i "adguard" /config/home-assistant.log
   

Test API Manually

# Test basic connectivity
curl -u admin:password http://192.168.1.100:3000/control/status

# Test client list
curl -u admin:password http://192.168.1.100:3000/control/clients

# Test statistics
curl -u admin:password http://192.168.1.100:3000/control/stats

📞 Getting Help

Before Seeking Support

1. ✅ Check this troubleshooting guide
2. ✅ Enable debug logging
3. ✅ Collect diagnostic information
4. ✅ Test with minimal configuration
5. ✅ Review recent changes

Where to Get Help

1. GitHub Issues: Repository Issues

   • Search existing issues first
   • Provide detailed information
   • Include logs and configuration

2. Home Assistant Community: Community Forum

   • General Home Assistant questions
   • Integration discussions

3. AdGuard Home Support: AdGuard Home GitHub

   • AdGuard Home specific issues
   • API-related questions

Issue Report Template

**Environment**:
- Home Assistant Version: 
- Integration Version: 
- AdGuard Home Version: 
- Installation Method: HACS/Manual

**Problem Description**:
Brief description of the issue

**Steps to Reproduce**:
1. Step one
2. Step two
3. Step three

**Expected Behavior**:
What you expected to happen

**Actual Behavior**:
What actually happened

**Logs**:

[Paste relevant logs here]

**Configuration**:
```yaml
# Paste relevant configuration (sanitize passwords)

## 🔧 Quick Fixes

### Reset Integration

```bash
# Complete reset
1. Remove integration from UI
2. Restart Home Assistant
3. rm -rf /config/custom_components/adguard_hub
4. Reinstall integration
5. Restart Home Assistant
6. Re-add integration

Emergency Recovery

# If automations are causing issues
# Disable automations temporarily
automation: []

# Or disable specific automation
automation old_automation_id:
  mode: single
  trigger: []
  action: []

Test Configuration

# Minimal test configuration
adguard_hub:
  scan_interval: 60
  auto_create_clients: false
  enable_statistics: false
  blocked_services_as_switches: false

---

Still having issues? Open an issue on the repository with detailed information, logs, and your configuration (remember to sanitize sensitive data).