homeassistant-mcp/docs/troubleshooting.md

---
layout: default
title: Troubleshooting
nav_order: 6
---

# Troubleshooting Guide 🔧

This guide helps you diagnose and resolve common issues with MCP Server.

## Quick Diagnostics

### Health Check

First, verify the server's health:

```bash
curl http://localhost:3000/health
```

Expected response:
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "homeAssistant": {
    "connected": true,
    "version": "2024.1.0"
  }
}
```

## Common Issues

### 1. Connection Issues

#### Cannot Connect to MCP Server

**Symptoms:**
- Server not responding
- Connection refused errors
- Timeout errors

**Solutions:**

1. Check if the server is running:
   ```bash
   # For Docker installation
   docker compose ps
   
   # For manual installation
   ps aux | grep mcp
   ```

2. Verify port availability:
   ```bash
   # Check if port is in use
   netstat -tuln | grep 3000
   ```

3. Check logs:
   ```bash
   # Docker logs
   docker compose logs mcp
   
   # Manual installation logs
   bun run dev
   ```

#### Home Assistant Connection Failed

**Symptoms:**
- "Connection Error" in health check
- Cannot control devices
- State updates not working

**Solutions:**

1. Verify Home Assistant URL and token in `.env`:
   ```env
   HA_URL=http://homeassistant:8123
   HA_TOKEN=your_long_lived_access_token
   ```

2. Test Home Assistant connection:
   ```bash
   curl -H "Authorization: Bearer YOUR_HA_TOKEN" \
        http://your-homeassistant:8123/api/
   ```

3. Check network connectivity:
   ```bash
   # For Docker setup
   docker compose exec mcp ping homeassistant
   ```

### 2. Authentication Issues

#### Invalid Token

**Symptoms:**
- 401 Unauthorized responses
- "Invalid token" errors

**Solutions:**

1. Generate a new token:
   ```bash
   curl -X POST http://localhost:3000/auth/token \
     -H "Content-Type: application/json" \
     -d '{"username": "your_username", "password": "your_password"}'
   ```

2. Verify token format:
   ```javascript
   // Token should be in format:
   Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
   ```

#### Rate Limiting

**Symptoms:**
- 429 Too Many Requests
- "Rate limit exceeded" errors

**Solutions:**

1. Check current rate limit status:
   ```bash
   curl -I http://localhost:3000/api/state
   ```

2. Adjust rate limits in configuration:
   ```yaml
   security:
     rateLimit: 100  # Increase if needed
     rateLimitWindow: 60000  # Window in milliseconds
   ```

### 3. Real-time Updates Issues

#### SSE Connection Drops

**Symptoms:**
- Frequent disconnections
- Missing state updates
- EventSource errors

**Solutions:**

1. Implement proper reconnection logic:
   ```javascript
   class SSEClient {
       constructor() {
           this.connect();
       }
   
       connect() {
           this.eventSource = new EventSource('/subscribe_events');
           this.eventSource.onerror = this.handleError.bind(this);
       }
   
       handleError(error) {
           console.error('SSE Error:', error);
           this.eventSource.close();
           setTimeout(() => this.connect(), 1000);
       }
   }
   ```

2. Check network stability:
   ```bash
   # Monitor connection stability
   ping -c 100 localhost
   ```

### 4. Performance Issues

#### High Latency

**Symptoms:**
- Slow response times
- Command execution delays
- UI lag

**Solutions:**

1. Enable Redis caching:
   ```env
   REDIS_ENABLED=true
   REDIS_URL=redis://localhost:6379
   ```

2. Monitor system resources:
   ```bash
   # Check CPU and memory usage
   docker stats
   
   # Or for manual installation
   top -p $(pgrep -f mcp)
   ```

3. Optimize database queries and caching:
   ```typescript
   // Use batch operations
   const results = await Promise.all([
       cache.get('key1'),
       cache.get('key2')
   ]);
   ```

### 5. Device Control Issues

#### Commands Not Executing

**Symptoms:**
- Commands appear successful but no device response
- Inconsistent device states
- Error messages from Home Assistant

**Solutions:**

1. Verify device availability:
   ```bash
   curl http://localhost:3000/api/state/light.living_room
   ```

2. Check command syntax:
   ```bash
   # Test basic command
   curl -X POST http://localhost:3000/api/command \
     -H "Content-Type: application/json" \
     -d '{"command": "Turn on living room lights"}'
   ```

3. Review Home Assistant logs:
   ```bash
   docker compose exec homeassistant journalctl -f
   ```

## Debugging Tools

### Log Analysis

Enable debug logging:

```env
LOG_LEVEL=debug
DEBUG=mcp:*
```

### Network Debugging

Monitor network traffic:

```bash
# TCP dump for API traffic
tcpdump -i any port 3000 -w debug.pcap
```

### Performance Profiling

Enable performance monitoring:

```env
ENABLE_METRICS=true
METRICS_PORT=9090
```

## Getting Help

If you're still experiencing issues:

1. Check the [GitHub Issues](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues)
2. Search [Discussions](https://github.com/jango-blockchained/advanced-homeassistant-mcp/discussions)
3. Create a new issue with:
   - Detailed description
   - Logs
   - Configuration (sanitized)
   - Steps to reproduce

## Maintenance

### Regular Health Checks

Run periodic health checks:

```bash
# Create a cron job
*/5 * * * * curl -f http://localhost:3000/health || notify-admin
```

### Log Rotation

Configure log rotation:

```yaml
logging:
  maxSize: "100m"
  maxFiles: "7d"
  compress: true
```

### Backup Configuration

Regularly backup your configuration:

```bash
# Backup script
tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
    .env \
    config/ \
    data/
```

## FAQ

### General Questions

#### Q: What is MCP Server?
A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.

#### Q: What are the system requirements?
A: MCP Server requires:
- Node.js 16 or higher
- Home Assistant instance
- 1GB RAM minimum
- 1GB disk space

#### Q: How do I update MCP Server?
A: For Docker installation:
```bash
docker compose pull
docker compose up -d
```
For manual installation:
```bash
git pull
bun install
bun run build
```

### Integration Questions

#### Q: Can I use MCP Server with any Home Assistant instance?
A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.

#### Q: Does MCP Server support all Home Assistant integrations?
A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.

### Security Questions

#### Q: Is my Home Assistant token secure?
A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.

#### Q: Can I use MCP Server remotely?
A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.

### Troubleshooting Questions

#### Q: Why are my device states not updating?
A: Check:
1. Home Assistant connection
2. WebSocket connection status
3. Device availability in Home Assistant
4. Network connectivity

#### Q: Why are my commands not working?
A: Verify:
1. Command syntax
2. Device availability
3. User permissions
4. Home Assistant API access