Add Troubleshooting
517
Troubleshooting.md
Normal file
517
Troubleshooting.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# 🔧 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**:
|
||||
```bash
|
||||
# Verify repository was added correctly
|
||||
# Go to HACS > Integrations > Menu > Custom repositories
|
||||
# Check if your repository URL is listed
|
||||
```
|
||||
|
||||
2. **Manual Installation**:
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
```yaml
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```yaml
|
||||
# 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**:
|
||||
```yaml
|
||||
# In configuration.yaml
|
||||
adguard_hub:
|
||||
scan_interval: 60 # Increase from default 30
|
||||
```
|
||||
|
||||
2. **Reduce Entity Count**:
|
||||
```yaml
|
||||
# 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**:
|
||||
```yaml
|
||||
adguard_hub:
|
||||
scan_interval: 120 # Reduce update frequency
|
||||
auto_create_clients: false # Manual client management
|
||||
```
|
||||
|
||||
2. **Check Logs**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Test DNS resolution
|
||||
nslookup adguard.local
|
||||
dig adguard.local
|
||||
```
|
||||
|
||||
3. **Update /etc/hosts**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# See what's using port 3000
|
||||
sudo lsof -i :3000
|
||||
netstat -tlnp | grep :3000
|
||||
```
|
||||
|
||||
2. **Change AdGuard Home Port**:
|
||||
```yaml
|
||||
# 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**:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo ufw status
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo firewall-cmd --list-all
|
||||
```
|
||||
|
||||
2. **Allow AdGuard Home Port**:
|
||||
```bash
|
||||
# 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):
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# 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**:
|
||||
```bash
|
||||
# In Home Assistant
|
||||
Settings > System > Repairs > Three dots > System Information
|
||||
```
|
||||
|
||||
2. **Integration Version**:
|
||||
```bash
|
||||
# Check manifest.json
|
||||
cat /config/custom_components/adguard_hub/manifest.json | grep version
|
||||
```
|
||||
|
||||
3. **AdGuard Home Version**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Extract relevant logs
|
||||
grep -i "adguard" /config/home-assistant.log
|
||||
```
|
||||
|
||||
### Test API Manually
|
||||
|
||||
```bash
|
||||
# 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](https://your-gitea-domain.com/your-username/adguard-control-hub/issues)
|
||||
- Search existing issues first
|
||||
- Provide detailed information
|
||||
- Include logs and configuration
|
||||
|
||||
2. **Home Assistant Community**: [Community Forum](https://community.home-assistant.io/)
|
||||
- General Home Assistant questions
|
||||
- Integration discussions
|
||||
|
||||
3. **AdGuard Home Support**: [AdGuard Home GitHub](https://github.com/AdguardTeam/AdGuardHome)
|
||||
- AdGuard Home specific issues
|
||||
- API-related questions
|
||||
|
||||
### Issue Report Template
|
||||
|
||||
```markdown
|
||||
**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
|
||||
|
||||
```yaml
|
||||
# If automations are causing issues
|
||||
# Disable automations temporarily
|
||||
automation: []
|
||||
|
||||
# Or disable specific automation
|
||||
automation old_automation_id:
|
||||
mode: single
|
||||
trigger: []
|
||||
action: []
|
||||
```
|
||||
|
||||
### Test Configuration
|
||||
|
||||
```yaml
|
||||
# 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).
|
||||
Reference in New Issue
Block a user