Troubleshooting

Troubleshooting

This page will help you resolve common issues with the Petkit integration.

🔧 Installation Issues

Integration Doesn't Appear in HACS

Possible Causes:

• Repository not added to custom repositories
• HACS not up to date
• Cache issues

Solutions:

1. Verify the repository is added in HACS
2. Refresh HACS: HACS → ⋮ → Reload
3. Clear browser cache
4. Restart Home Assistant

Installation Error

Typical Error Message: "Installation failed"

Solutions:

1. Check available disk space
2. Check internet connection
3. Check Home Assistant logs
4. Install manually if necessary

🔑 Connection Issues

Authentication Failure

Possible Causes:

• Incorrect credentials
• Account used simultaneously in official app
• Wrong region configured
• Network issues

Solutions:

1. Verify your Petkit credentials
2. Use a secondary account (see Configuration)
3. Check selected region:
   • Europe: eu
   • North America: us
   • Asia: as
4. Test connection from official Petkit app

Unstable Connection

Symptoms:

• Frequent disconnections
• Entities unavailable intermittently
• High response delays

Solutions:

1. Increase polling interval (90-120 seconds)
2. Temporarily disable smart polling
3. Check internet connection stability
4. Restart the integration

📱 Device Issues

Device Not Detected

Checks:

1. Is the device connected to the Petkit app?
2. Is the device in the supported devices list?
3. Is the device online in the official app?

Solutions:

1. Restart the Petkit device
2. Check device WiFi connection
3. Remove and re-add device in Petkit app
4. Restart HA integration

Missing Entities

Possible Causes:

• Partially supported device
• Synchronization issue
• Incomplete configuration

Solutions:

1. Wait 5-10 minutes after adding
2. Restart the integration
3. Check logs for specific errors
4. Enable debug mode

Commands Not Working

Common Issues:

• Buttons/switches with no effect
• Commands with significant delay
• Errors in logs

Solutions:

1. Verify device is online
2. Test command from official app
3. Wait between commands (API limits)
4. Restart device if necessary

🎬 Media Issues

Images/Videos Not Downloading

Checks:

1. Option enabled in configuration?
2. Care+ subscription active (for videos)?
3. Sufficient storage space?
4. Write permissions on directory?

Solutions:

1. Check media configuration
2. Test with different directory
3. Check system permissions
4. Check detailed logs

Storage Path Errors

Common Error Messages:

• "Permission denied"
• "Path not found"
• "Cannot create directory"

Solutions:

1. Use absolute path: /media/petkit
2. Check case sensitivity
3. Create directory manually
4. Check HA permissions

Corrupted or Empty Media

Causes:

• Download interruption
• Network issues
• Corrupted source file

Solutions:

1. Delete corrupted files
2. Restart synchronization
3. Check network stability
4. Reduce refresh interval

🔵 Bluetooth Issues

Bluetooth Fountains Not Detected

Prerequisites:

• Bluetooth relay device nearby
• HA Bluetooth integration active
• Compatible fountain

Solutions:

1. Check physical proximity
2. Restart HA Bluetooth integration
3. Reset fountain
4. Check Bluetooth logs

Unstable Bluetooth Connection

Improvements:

1. Reduce fountain/relay distance
2. Eliminate interference (other Bluetooth)
3. Increase scan interval
4. Use dedicated Bluetooth adapter

📊 Performance Issues

Too Frequent Polling

Symptoms:

• Saturated logs
• HA sluggish
• API limits reached

Solutions:

1. Increase polling interval
2. Temporarily disable smart polling
3. Limit number of devices
4. Check resource-heavy automations

Slow Entity Updates

Optimizations:

1. Enable smart polling
2. Reduce interval for active devices
3. Check network latency
4. Restart integration periodically

🛠️ Diagnostic Tools

Enable Debug Mode

1. Go to Configuration → Integrations
2. Find "Petkit Smart Devices"
3. Click "Configure" → "Enable debug"

Or add to configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.petkit: debug

Useful Information for Support

When asking for help, provide:

• HA Version: About in HA
• Integration Version: In HACS
• Device Model: Exact name
• Error Logs: Debug mode enabled
• Configuration: Anonymized settings
• Reproduction: Steps to reproduce

Important Logs to Monitor

2025-09-19 08:57:00 ERROR (MainThread) [custom_components.petkit] 
2025-09-19 08:57:00 WARNING (MainThread) [custom_components.petkit.api]
2025-09-19 08:57:00 DEBUG (MainThread) [custom_components.petkit.coordinator]

🔄 Workarounds

Soft Restart

If integration gets stuck:

1. Settings → Devices & Services
2. Find "Petkit Smart Devices"
3. Click ⋮ → Reload

Complete Reset

For major issues:

1. Remove integration
2. Restart Home Assistant
3. Reinstall integration
4. Reconfigure carefully

Issue Isolation

To identify the cause:

1. Temporarily disable other integrations
2. Test with single device
3. Use test Petkit account
4. Check on clean HA installation

🆘 Getting Help

Community

• 💬 Discord: Join
• 🏠 HA Forum: Community Forum

Technical Support

• 🐛 GitHub Issues: Open Issue
• 📖 Documentation: Complete Wiki

Before Asking for Help

1. ✅ Check this troubleshooting page
2. ✅ Enable debug mode
3. ✅ Reproduce the issue
4. ✅ Collect error logs
5. ✅ Prepare system information

Bug Report Format

**Issue:** Short description

**Configuration:**
- HA: Version X.X.X
- Integration: Version X.X.X
- Device: Exact model

**Logs:**

[Paste logs here]

**Reproduction:**
1. Step 1
2. Step 2
3. Expected vs actual result

Most issues are resolved quickly with this information!

🔮 Issue Prevention

Best Practices

• 🔄 Regular integration updates
• 📊 Performance monitoring
• 💾 Configuration backups
• 🔍 Periodic log checking
• 📱 Regular functionality testing

Preventive Monitoring

Create automations to monitor:

• Entity availability
• API error frequency
• Storage space usage
• Query performance