Skip to content

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:

  1. Verify HA_URL is correct:
  2. Check the URL format: http://hostname:port or https://hostname:port
  3. Ensure the port is correct (default: 8123)
  4. Test the URL in a browser

  5. Check network connectivity:

  6. Ping the Home Assistant host
  7. Verify firewall rules allow connections
  8. For Docker, check network configuration

  9. Verify Home Assistant is running:

  10. Check Home Assistant status
  11. Ensure API is enabled (enabled by default)

Problem: "401 Unauthorized" or "403 Forbidden"

Symptoms: - Authentication errors - "Invalid token" messages

Solutions:

  1. Verify HA_TOKEN is correct:
  2. Check token hasn't been revoked
  3. Ensure token is copied completely
  4. Try creating a new token

  5. Check token permissions:

  6. Ensure token has necessary permissions
  7. Some operations may require admin permissions

  8. Token expiration:

  9. Long-lived tokens don't expire by default
  10. Check if token was set with expiration

Tool-Specific Issues

Problem: Entity Not Found

Symptoms: - "Entity not found" errors - Entity appears as unavailable

Solutions:

  1. Verify entity ID format:
  2. Format: domain.entity_name
  3. Example: light.living_room
  4. Check for typos

  5. Check entity exists:

  6. Use list_entities to find the correct ID
  7. Use search_entities_tool to find similar entities

  8. Check entity state:

  9. Entity may be unavailable
  10. Use diagnose_entity to investigate

Problem: Automation Not Working

Symptoms: - Automation doesn't trigger - Automation fails to execute

Solutions:

  1. Check automation status:
  2. Use get_automation_config to verify configuration
  3. Check if automation is enabled
  4. Review execution logs with get_automation_execution_log

  5. Verify triggers:

  6. Check trigger conditions
  7. Verify trigger entities exist and are working
  8. Test trigger conditions manually

  9. Check conditions:

  10. Review condition logic
  11. Verify condition entities are in correct states

  12. Review actions:

  13. Verify action entities exist
  14. Check for errors in action execution

Problem: Service Call Fails

Symptoms: - Service calls return errors - "Service not found" messages

Solutions:

  1. Verify service name:
  2. Format: domain.service
  3. Check service documentation for correct name

  4. Check service parameters:

  5. Review required parameters
  6. Verify parameter types (string, number, etc.)
  7. Check parameter values are valid

  8. Verify entity exists:

  9. If service requires entity_id, verify it exists
  10. 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:

  1. Increase timeout:
  2. Set HA_TIMEOUT environment variable
  3. Default is 30 seconds, increase if needed

  4. Use lean format:

  5. Use lean=True when listing entities
  6. Specify limit to reduce result size

  7. Filter results:

  8. Use domain filters
  9. Use search queries instead of listing all entities

  10. Check Home Assistant performance:

  11. Review Home Assistant logs
  12. Check system resources
  13. Review integration performance

Problem: High Token Usage

Symptoms: - Conversations consume many tokens - Responses are too verbose

Solutions:

  1. Use lean format:
  2. Default format is already lean
  3. Avoid detailed=True unless necessary

  4. Limit results:

  5. Use limit parameter
  6. Use domain filters

  7. Be specific:

  8. Ask for specific entities
  9. 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:

  1. Use host.docker.internal:
  2. For Mac/Windows Docker Desktop
  3. Use http://host.docker.internal:8123

  4. Use host network (Linux only):

  5. Add --network host to Docker args
  6. Allows container to use host network

  7. Use actual IP address:

  8. Instead of hostname, use IP address
  9. Example: http://192.168.1.100:8123

  10. Check Docker network:

  11. Verify Docker network configuration
  12. Ensure container can reach host network

Problem: Environment Variables Not Working

Symptoms: - Tools fail with "missing configuration" errors

Solutions:

  1. Verify environment variable format:
  2. Use -e flag in Docker args
  3. Format: -e HA_URL -e HA_TOKEN

  4. Check Claude Desktop configuration:

  5. Verify env section is correct
  6. Ensure JSON is valid

  7. Test environment variables:

  8. Check variables are passed correctly
  9. Review Docker logs for errors

Getting Additional Help

Debug Mode

Enable debug logging:

{
  "env": {
    "LOG_LEVEL": "DEBUG"
  }
}

This provides detailed logging for troubleshooting.

Check Logs

  1. Claude Desktop logs:
  2. Check Claude Desktop console for errors
  3. Review MCP server connection logs

  4. Home Assistant logs:

  5. Check Home Assistant logs for API errors
  6. Review integration logs

  7. Docker logs:

  8. docker logs <container-id>
  9. 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:

  1. Error messages: Exact error text
  2. Configuration: Relevant parts (without tokens!)
  3. Steps to reproduce: What you did to trigger the issue
  4. Environment: Home Assistant version, Python version, etc.
  5. Logs: Relevant log entries (sanitize tokens!)