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