Troubleshooting
Common issues and their solutions when using Hass-MCP.
Connection Issues
Problem: "Cannot connect to Home Assistant"
Symptoms: - Tools fail with connection errors - "Connection timeout" messages - "Connection refused" errors
Solutions:
- Verify
HA_URLis correct: - Check the URL format:
http://hostname:portorhttps://hostname:port - Ensure the port is correct (default: 8123)
-
Test the URL in a browser
-
Check network connectivity:
- Ping the Home Assistant host
- Verify firewall rules allow connections
-
For Docker, check network configuration
-
Verify Home Assistant is running:
- Check Home Assistant status
- Ensure API is enabled (enabled by default)
Problem: "401 Unauthorized" or "403 Forbidden"
Symptoms: - Authentication errors - "Invalid token" messages
Solutions:
- Verify
HA_TOKENis correct: - Check token hasn't been revoked
- Ensure token is copied completely
-
Try creating a new token
-
Check token permissions:
- Ensure token has necessary permissions
-
Some operations may require admin permissions
-
Token expiration:
- Long-lived tokens don't expire by default
- Check if token was set with expiration
Tool-Specific Issues
Problem: Entity Not Found
Symptoms: - "Entity not found" errors - Entity appears as unavailable
Solutions:
- Verify entity ID format:
- Format:
domain.entity_name - Example:
light.living_room -
Check for typos
-
Check entity exists:
- Use
list_entitiesto find the correct ID -
Use
search_entities_toolto find similar entities -
Check entity state:
- Entity may be unavailable
- Use
diagnose_entityto investigate
Problem: Automation Not Working
Symptoms: - Automation doesn't trigger - Automation fails to execute
Solutions:
- Check automation status:
- Use
get_automation_configto verify configuration - Check if automation is enabled
-
Review execution logs with
get_automation_execution_log -
Verify triggers:
- Check trigger conditions
- Verify trigger entities exist and are working
-
Test trigger conditions manually
-
Check conditions:
- Review condition logic
-
Verify condition entities are in correct states
-
Review actions:
- Verify action entities exist
- Check for errors in action execution
Problem: Service Call Fails
Symptoms: - Service calls return errors - "Service not found" messages
Solutions:
- Verify service name:
- Format:
domain.service -
Check service documentation for correct name
-
Check service parameters:
- Review required parameters
- Verify parameter types (string, number, etc.)
-
Check parameter values are valid
-
Verify entity exists:
- If service requires
entity_id, verify it exists - Check entity is in a state that allows the service call
Performance Issues
Problem: Slow Response Times
Symptoms: - Tools take a long time to execute - Timeout errors
Solutions:
- Increase timeout:
- Set
HA_TIMEOUTenvironment variable -
Default is 30 seconds, increase if needed
-
Use lean format:
- Use
lean=Truewhen listing entities -
Specify
limitto reduce result size -
Filter results:
- Use domain filters
-
Use search queries instead of listing all entities
-
Check Home Assistant performance:
- Review Home Assistant logs
- Check system resources
- Review integration performance
Problem: High Token Usage
Symptoms: - Conversations consume many tokens - Responses are too verbose
Solutions:
- Use lean format:
- Default format is already lean
-
Avoid
detailed=Trueunless necessary -
Limit results:
- Use
limitparameter -
Use domain filters
-
Be specific:
- Ask for specific entities
- Use search instead of listing all
Docker-Specific Issues
Problem: Docker Container Can't Reach Home Assistant
Symptoms: - Connection errors from Docker container - "Connection refused" from container
Solutions:
- Use
host.docker.internal: - For Mac/Windows Docker Desktop
-
Use
http://host.docker.internal:8123 -
Use host network (Linux only):
- Add
--network hostto Docker args -
Allows container to use host network
-
Use actual IP address:
- Instead of hostname, use IP address
-
Example:
http://192.168.1.100:8123 -
Check Docker network:
- Verify Docker network configuration
- Ensure container can reach host network
Problem: Environment Variables Not Working
Symptoms: - Tools fail with "missing configuration" errors
Solutions:
- Verify environment variable format:
- Use
-eflag in Docker args -
Format:
-e HA_URL -e HA_TOKEN -
Check Claude Desktop configuration:
- Verify
envsection is correct -
Ensure JSON is valid
-
Test environment variables:
- Check variables are passed correctly
- Review Docker logs for errors
Getting Additional Help
Debug Mode
Enable debug logging:
This provides detailed logging for troubleshooting.
Check Logs
- Claude Desktop logs:
- Check Claude Desktop console for errors
-
Review MCP server connection logs
-
Home Assistant logs:
- Check Home Assistant logs for API errors
-
Review integration logs
-
Docker logs:
docker logs <container-id>- Review container output
Community Resources
- GitHub Issues: Report bugs or ask questions
- Home Assistant Forums: Community support
- Home Assistant Discord: Real-time help
Reporting Issues
When reporting issues, include:
- Error messages: Exact error text
- Configuration: Relevant parts (without tokens!)
- Steps to reproduce: What you did to trigger the issue
- Environment: Home Assistant version, Python version, etc.
- Logs: Relevant log entries (sanitize tokens!)