diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..cc2f1f8
--- /dev/null
+++ b/Troubleshooting.md
@@ -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).
\ No newline at end of file