18f09bb5ce
- Created detailed getting started guide with installation and configuration instructions - Added main documentation README with structured table of contents - Developed troubleshooting guide with common issues, debugging tips, and FAQ - Included development guide with project structure, setup, and contribution guidelines - Added tools documentation with overview of available management tools
193 lines
3.5 KiB
Markdown
193 lines
3.5 KiB
Markdown
# 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:
|
|
```env
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
2. Check logs:
|
|
```bash
|
|
npm run logs
|
|
```
|
|
|
|
3. Filter logs:
|
|
```bash
|
|
npm run logs | grep "error"
|
|
```
|
|
|
|
### Network Debugging
|
|
|
|
1. Check API endpoints:
|
|
```bash
|
|
curl -v http://localhost:3000/api/health
|
|
```
|
|
|
|
2. Monitor SSE connections:
|
|
```bash
|
|
curl -N http://localhost:3000/api/sse/stats
|
|
```
|
|
|
|
3. Test WebSocket:
|
|
```bash
|
|
wscat -c ws://localhost:3000
|
|
```
|
|
|
|
### Performance Issues
|
|
|
|
1. Monitor memory usage:
|
|
```bash
|
|
npm run stats
|
|
```
|
|
|
|
2. Check response times:
|
|
```bash
|
|
curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
|
|
```
|
|
|
|
3. Profile code:
|
|
```bash
|
|
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](./API.md)
|
|
- [Configuration Guide](./configuration/README.md)
|
|
- [Development Guide](./development/README.md)
|
|
|
|
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 |