sq4ind/adguard-control-hub
1
0 Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity
Page: Troubleshooting
Pages
API-Reference Automation-Examples Changelog Configuration Contributing Dashboard-Examples Development Home Installation Service-Reference Troubleshooting
Clone
1
Troubleshooting
sq4ind edited this page 2025-09-28 12:46:04 +00:00
Table of Contents

🔧 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).