homeassistant-mcp/docs/troubleshooting.md

Troubleshooting Guide

This guide helps you diagnose and fix common issues with the Home Assistant MCP.

Common Issues

Connection Issues

Cannot Connect to Home Assistant

Symptoms:

• Connection timeout errors
• "Failed to connect to Home Assistant" messages
• 401 Unauthorized errors

Solutions:

1. Verify Home Assistant is running
2. Check HASS_HOST environment variable
3. Validate HASS_TOKEN is correct
4. Ensure network connectivity
5. Check firewall settings

SSE Connection Drops

Symptoms:

• Frequent disconnections
• Missing events
• Connection reset errors

Solutions:

1. Check network stability
2. Increase connection timeout
3. Implement reconnection logic
4. Monitor server resources

Authentication Issues

Invalid Token

Symptoms:

• 401 Unauthorized responses
• "Invalid token" messages
• Authentication failures

Solutions:

1. Generate new Long-Lived Access Token
2. Check token expiration
3. Verify token format
4. Update environment variables

Rate Limiting

Symptoms:

• 429 Too Many Requests
• "Rate limit exceeded" messages

Solutions:

1. Implement request throttling
2. Adjust rate limit settings
3. Cache responses
4. Optimize request patterns

Tool Issues

Tool Not Found

Symptoms:

• "Tool not found" errors
• 404 Not Found responses

Solutions:

1. Check tool name spelling
2. Verify tool registration
3. Update tool imports
4. Check tool availability

Tool Execution Fails

Symptoms:

• Tool execution errors
• Unexpected responses
• Timeout issues

Solutions:

1. Validate input parameters
2. Check error logs
3. Debug tool implementation
4. Verify Home Assistant permissions

Debugging

Server Logs

1. Enable debug logging:

   LOG_LEVEL=debug
   

2. Check logs:

   npm run logs
   

3. Filter logs:

   npm run logs | grep "error"
   

Network Debugging

1. Check API endpoints:

   curl -v http://localhost:3000/api/health
   

2. Monitor SSE connections:

   curl -N http://localhost:3000/api/sse/stats
   

3. Test WebSocket:

   wscat -c ws://localhost:3000
   

Performance Issues

1. Monitor memory usage:

   npm run stats
   

2. Check response times:

   curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
   

3. Profile code:

   npm run profile
   

FAQ

Q: How do I reset my configuration?

A: Delete .env and copy .env.example to start fresh.

Q: Why are my events delayed?

A: Check network latency and server load. Consider adjusting buffer sizes.

Q: How do I update my token?

A: Generate a new token in Home Assistant and update HASS_TOKEN.

Q: Why do I get "Maximum clients reached"?

A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.

Error Codes

• E001: Connection Error
• E002: Authentication Error
• E003: Rate Limit Error
• E004: Tool Error
• E005: Configuration Error

Support Resources

1. Documentation

   • API Reference
   • Configuration Guide
   • Development Guide

2. Community

   • GitHub Issues
   • Discussion Forums
   • Stack Overflow

3. Tools

   • Diagnostic Scripts
   • Testing Tools
   • Monitoring Tools

Still Need Help?

1. Create a detailed issue:

   • Error messages
   • Steps to reproduce
   • Environment details
   • Logs

2. Contact support:

   • GitHub Issues
   • Email Support
   • Community Forums