docs: add comprehensive documentation for MCP project
- Create comprehensive documentation structure using MkDocs - Add markdown files for API reference, architecture, getting started, and troubleshooting - Configure GitHub Pages deployment workflow - Include custom Jekyll and MkDocs configurations - Add custom styling and layout for documentation site
This commit is contained in:
jango-blockchained
354
docs/troubleshooting.md
Normal file
354
docs/troubleshooting.md
Normal file
@@ -0,0 +1,354 @@
|
||||
# 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
|
||||
|
||||
## Security Middleware Troubleshooting
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
#### Rate Limiting Problems
|
||||
|
||||
**Symptom**: Unexpected 429 (Too Many Requests) errors
|
||||
|
||||
**Possible Causes**:
|
||||
- Misconfigured rate limit settings
|
||||
- Shared IP addresses (e.g., behind NAT)
|
||||
- Aggressive client-side retry mechanisms
|
||||
|
||||
**Solutions**:
|
||||
1. Adjust rate limit parameters
|
||||
```typescript
|
||||
// Customize rate limit for specific scenarios
|
||||
checkRateLimit(ip, maxRequests = 200, windowMs = 30 * 60 * 1000)
|
||||
```
|
||||
|
||||
2. Implement more granular rate limiting
|
||||
- Use different limits for different endpoints
|
||||
- Consider user authentication level
|
||||
|
||||
#### Request Validation Failures
|
||||
|
||||
**Symptom**: 400 or 415 status codes on valid requests
|
||||
|
||||
**Possible Causes**:
|
||||
- Incorrect `Content-Type` header
|
||||
- Large request payloads
|
||||
- Malformed authorization headers
|
||||
|
||||
**Debugging Steps**:
|
||||
1. Verify request headers
|
||||
```typescript
|
||||
// Check content type and size
|
||||
validateRequestHeaders(request, 'application/json')
|
||||
```
|
||||
|
||||
2. Log detailed validation errors
|
||||
```typescript
|
||||
try {
|
||||
validateRequestHeaders(request);
|
||||
} catch (error) {
|
||||
console.error('Request validation failed:', error.message);
|
||||
}
|
||||
```
|
||||
|
||||
#### Input Sanitization Issues
|
||||
|
||||
**Symptom**: Unexpected data transformation or loss
|
||||
|
||||
**Possible Causes**:
|
||||
- Complex nested objects
|
||||
- Non-standard input formats
|
||||
- Overly aggressive sanitization
|
||||
|
||||
**Troubleshooting**:
|
||||
1. Test sanitization with various input types
|
||||
```typescript
|
||||
const input = {
|
||||
text: '<script>alert("xss")</script>',
|
||||
nested: { html: '<img src="x" onerror="alert(1)">World' }
|
||||
};
|
||||
const sanitized = sanitizeValue(input);
|
||||
```
|
||||
|
||||
2. Custom sanitization for specific use cases
|
||||
```typescript
|
||||
function customSanitize(value) {
|
||||
// Add custom sanitization logic
|
||||
return sanitizeValue(value);
|
||||
}
|
||||
```
|
||||
|
||||
#### Security Header Configuration
|
||||
|
||||
**Symptom**: Missing or incorrect security headers
|
||||
|
||||
**Possible Causes**:
|
||||
- Misconfigured Helmet options
|
||||
- Environment-specific header requirements
|
||||
|
||||
**Solutions**:
|
||||
1. Custom security header configuration
|
||||
```typescript
|
||||
const customHelmetConfig = {
|
||||
contentSecurityPolicy: {
|
||||
directives: {
|
||||
defaultSrc: ["'self'"],
|
||||
scriptSrc: ["'self'", 'trusted-cdn.com']
|
||||
}
|
||||
}
|
||||
};
|
||||
applySecurityHeaders(request, customHelmetConfig);
|
||||
```
|
||||
|
||||
#### Error Handling and Logging
|
||||
|
||||
**Symptom**: Inconsistent error responses
|
||||
|
||||
**Possible Causes**:
|
||||
- Incorrect environment configuration
|
||||
- Unhandled error types
|
||||
|
||||
**Debugging Techniques**:
|
||||
1. Verify environment settings
|
||||
```typescript
|
||||
const errorResponse = handleError(error, process.env.NODE_ENV);
|
||||
```
|
||||
|
||||
2. Add custom error handling
|
||||
```typescript
|
||||
function enhancedErrorHandler(error, env) {
|
||||
// Add custom logging or monitoring
|
||||
console.error('Security error:', error);
|
||||
return handleError(error, env);
|
||||
}
|
||||
```
|
||||
|
||||
### Performance and Security Monitoring
|
||||
|
||||
1. **Logging**
|
||||
- Enable debug logging for security events
|
||||
- Monitor rate limit and validation logs
|
||||
|
||||
2. **Metrics**
|
||||
- Track rate limit hit rates
|
||||
- Monitor request validation success/failure ratios
|
||||
|
||||
3. **Continuous Improvement**
|
||||
- Regularly review and update security configurations
|
||||
- Conduct periodic security audits
|
||||
|
||||
### Environment-Specific Considerations
|
||||
|
||||
#### Development
|
||||
- More verbose error messages
|
||||
- Relaxed rate limiting
|
||||
- Detailed security logs
|
||||
|
||||
#### Production
|
||||
- Minimal error details
|
||||
- Strict rate limiting
|
||||
- Comprehensive security headers
|
||||
|
||||
### External Resources
|
||||
|
||||
- [OWASP Security Guidelines](https://owasp.org/www-project-top-ten/)
|
||||
- [Helmet.js Documentation](https://helmetjs.github.io/)
|
||||
- [JWT Security Best Practices](https://jwt.io/introduction)
|
||||
|
||||
### Getting Help
|
||||
|
||||
If you encounter persistent issues:
|
||||
1. Check application logs
|
||||
2. Verify environment configurations
|
||||
3. Consult the project's issue tracker
|
||||
4. Reach out to the development team with detailed error information
|
||||
Reference in New Issue
Block a user