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

python
1# Symptoms:
2# - "coroutine was never awaited"
3# - Event loop blocking
4# - Timeouts
5
6# Check for:
7await missing_function()  # Missing await
8blocking_io_call()  # Blocking I/O in async context

2. Home Assistant Integration Errors

python
1# Symptoms:
2# - Integration fails to load
3# - Config flow errors
4# - Entity not showing up
5
6# Check for:
7# - Missing async_setup_entry/async_unload_entry
8# - Incorrect platform registration
9# - Missing unique_id on entities
10# - Data not stored in hass.data correctly

3. API/Network Errors

python
1# Symptoms:
2# - Connection refused
3# - Timeouts
4# - 4xx/5xx HTTP errors
5
6# Check for:
7# - Supabase URL/key configuration
8# - Network connectivity
9# - API rate limits
10# - 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:

bash
1# Home Assistant logs
2tail -f /config/home-assistant.log | grep linus
3
4# Check for warnings
5grep -i "warning.*linus" /config/home-assistant.log

Add Debug Logging:

python
1import logging
2_LOGGER = logging.getLogger(__name__)
3
4_LOGGER.debug("Variable value: %s", variable)
5_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

python
1# Before
2result = async_function()
3
4# After
5result = await async_function()

Issue: Integration doesn't load

Solution: Check entry setup and platform registration

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

Issue: Entity not updating

Solution: Verify state updates and coordinator refresh

python
1# Ensure coordinator updates
2await self.coordinator.async_request_refresh()

Issue: Timeout errors

Solution: Increase timeout or optimize slow operations

python
1# Add proper timeout
2async with timeout(30):
3    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:

python
1# Add breakpoint (if debugging locally)
2import pdb; pdb.set_trace()
3
4# Add detailed logging
5_LOGGER.debug("State: %s, Attrs: %s", self.state, self.extra_state_attributes)

Git Tools:

bash
1# Find when bug was introduced
2git log --oneline -- path/to/file.py
3
4# Check recent changes
5git 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