debug

name	debug
description	Debug errors, bugs, and unexpected behavior systematically in Home Assistant integration. Use when investigating errors, analyzing stack traces, fixing bugs, or troubleshooting unexpected behavior.

Debug Errors and Bugs Systematically

Debug errors, bugs, and unexpected behavior in the Linus Dashboard Home Assistant integration.

---

Context Loading

Before debugging, load:

1. .aidriven/memorybank.md - Project architecture
2. .aidriven/rules/clean_code.md - Code standards
3. .aidriven/rules/homeassistant_integration.md - HA patterns
4. .aidriven/rules/async_patterns.md - Async best practices

---

Debug Process

Step 1: Understand the Error

Collect Information:

• Error message (full stack trace)
• When does it occur? (startup, service call, state change)
• Which file/function is involved?
• User actions that trigger it
• Home Assistant version and logs

Questions to Ask:

1. Is this a Python exception or HA-specific error?
2. Does the error occur consistently or randomly?
3. Are there related errors in home-assistant.log?
4. What changed recently (code, config, HA version)?

Step 2: Analyze Root Cause

Common Error Categories:

1. Async/Await Issues

# Symptoms:
# - "coroutine was never awaited"
# - Event loop blocking
# - Timeouts

# Check for:
await missing_function()  # Missing await
blocking_io_call()  # Blocking I/O in async context

2. Home Assistant Integration Errors

# Symptoms:
# - Integration fails to load
# - Config flow errors
# - Entity not showing up

# Check for:
# - Missing async_setup_entry/async_unload_entry
# - Incorrect platform registration
# - Missing unique_id on entities
# - Data not stored in hass.data correctly

3. API/Network Errors

# Symptoms:
# - Connection refused
# - Timeouts
# - 4xx/5xx HTTP errors

# Check for:
# - Supabase URL/key configuration
# - Network connectivity
# - API rate limits
# - Timeout values

Step 3: Investigate

Review Code:

• Read the file where error occurs
• Trace the execution path
• Check function signatures
• Review recent changes with git log

Check Logs:

# Home Assistant logs
tail -f /config/home-assistant.log | grep linus

# Check for warnings
grep -i "warning.*linus" /config/home-assistant.log

Add Debug Logging:

import logging
_LOGGER = logging.getLogger(__name__)

_LOGGER.debug("Variable value: %s", variable)
_LOGGER.info("Entering function with args: %s", args)

Step 4: Fix the Issue

Apply Fix:

• Make minimal changes to fix root cause
• Follow code standards from .aidriven/rules/clean_code.md
• Add error handling if missing
• Update documentation if behavior changed

Test the Fix:

1. Restart Home Assistant
2. Reproduce the original error scenario
3. Verify error is gone
4. Check logs for new errors
5. Test related functionality

Step 5: Verify and Document

Verification:

• Error no longer occurs
• No new errors introduced
• Related features still work
• Logs are clean

Documentation:

• Update inline comments if needed
• Note the fix in commit message
• Update CHANGELOG if user-facing

---

Common Issues and Solutions

Issue: "coroutine was never awaited"

Solution: Add await before async function calls

# Before
result = async_function()

# After
result = await async_function()

Issue: Integration doesn't load

Solution: Check entry setup and platform registration

# Ensure proper setup
async def async_setup_entry(hass, entry):
    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
    return True

Issue: Entity not updating

Solution: Verify state updates and coordinator refresh

# Ensure coordinator updates
await self.coordinator.async_request_refresh()

Issue: Timeout errors

Solution: Increase timeout or optimize slow operations

# Add proper timeout
async with timeout(30):
    result = await slow_operation()

---

Debug Tools

Home Assistant Developer Tools:

• Services tab - Test service calls
• States tab - Check entity states
• Events tab - Monitor events
• Template tab - Test templates

Python Debugging:

# Add breakpoint (if debugging locally)
import pdb; pdb.set_trace()

# Add detailed logging
_LOGGER.debug("State: %s, Attrs: %s", self.state, self.extra_state_attributes)

Git Tools:

# Find when bug was introduced
git log --oneline -- path/to/file.py

# Check recent changes
git diff HEAD~5 -- path/to/file.py

---

Checklist

Before completing debug:

• Root cause identified
• Fix implemented following code standards
• Error no longer reproduces
• Related functionality tested
• Logs reviewed for new issues
• Changes documented