Skip to content

Improve error message when load_xml_db fails to connect to controller#118

Open
mortms wants to merge 1 commit into
thecynic:masterfrom
mortms:improve-xml-db-fetch-error-message
Open

Improve error message when load_xml_db fails to connect to controller#118
mortms wants to merge 1 commit into
thecynic:masterfrom
mortms:improve-xml-db-fetch-error-message

Conversation

@mortms

@mortms mortms commented Mar 16, 2026

Copy link
Copy Markdown

PR: Improve error messaging when XML database fetch fails

PR Description

Problem

When load_xml_db() fails to fetch the XML database from the Lutron controller
(e.g., due to an incorrect IP address, network misconfiguration, or an
unresponsive controller), the user sees a raw Python urllib.error.URLError
traceback with TimeoutError: [Errno 110] Operation timed out.

This error gives no indication of what IP address was being contacted or
what the user should check to resolve the issue. In Home Assistant, this
surfaces as:

Error setting up entry Lutron for lutron
...
urllib.error.URLError: <urlopen error [Errno 110] Operation timed out>

Users facing this error have to dig through source code to understand that the
integration is trying to reach the controller's HTTP server to download the XML
database, and that the configured IP address may simply be wrong.

Solution

This PR wraps the urlopen call in load_xml_db() with a try/except that
catches urllib.error.URLError and raises a ConnectionError with a clear,
actionable message that includes:

  • The full URL that was attempted
  • The configured controller IP address
  • A suggestion to verify the IP and controller reachability
  • The original underlying error for debugging

Additionally, an explicit timeout=30 is added to the urlopen call to avoid
relying on the system default socket timeout, which can vary across platforms
and lead to inconsistent behavior.

Example error output (after this change)

ConnectionError: Unable to fetch Lutron XML database from
http://192.168.1.100/DbXmlInfo.xml. Verify that the controller IP address
'192.168.1.100' is correct and that the controller is reachable on port 80.
Original error: <urlopen error [Errno 110] Operation timed out>

Change summary

  • Wrap urlopen in load_xml_db() with try/except for urllib.error.URLError
  • Raise ConnectionError with a descriptive message including the URL and host
  • Add explicit timeout=30 to urlopen call

Testing

Tested with Home Assistant 2026.2.3 on HA OS with a Lutron RadioRA 2 system.
Verified that:

  • Normal operation (correct IP) is unaffected
  • Incorrect IP now produces a clear, actionable error message
  • The timeout parameter works as expected

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant