Skip to content

Include underlying error details in commissioning failure messages#1344

Open
BrianHotopp wants to merge 1 commit intomatter-js:mainfrom
BrianHotopp:fix/improve-commissioning-error-messages
Open

Include underlying error details in commissioning failure messages#1344
BrianHotopp wants to merge 1 commit intomatter-js:mainfrom
BrianHotopp:fix/improve-commissioning-error-messages

Conversation

@BrianHotopp
Copy link

Summary

When Matter commissioning fails, the ChipStackError from the CHIP SDK is caught and re-raised as NodeCommissionFailed with a generic message like "Commission with code failed for node 42." — the specific error (e.g. invalid pairing code checksum, wrong code length, Bluetooth not available, WiFi network not found) is discarded. Users have to enable debug logging and read tracebacks to find out why commissioning failed.

This PR propagates the original error message into all commissioning-related exceptions:

  • NodeCommissionFailed in commission_with_code and commission_on_network — appends : {err} so the CHIP SDK error reason is visible
  • NodeInterviewFailed in _interview_node — same treatment
  • NodeNotResolving in sdk.py CASE session establishment — same treatment
  • Bluetooth availability check — expands the one-line message with a hint to configure a Bluetooth adapter or use network_only mode

Motivation

While commissioning a Matter device (Brighter lamp) via Home Assistant, every failure showed the same unhelpful message: "Commission with code failed for node X". The actual errors — invalid pairing code checksum, wrong code length, Bluetooth not configured, WiFi network not found — were only visible in verbose server logs. I had to read the python-matter-server source to understand the error wrapping chain. This small change makes commissioning failures self-diagnosable directly from the Home Assistant UI.

Before

Commission with code failed for node 42.

After

Commission with code failed for node 42: ChipStackError: CHIP Error 0x0000002F: Integrity check failed

Changes

  • matter_server/server/device_controller.py: Include {err} in NodeCommissionFailed and NodeInterviewFailed messages; expand Bluetooth error with actionable guidance
  • matter_server/server/sdk.py: Include {err} in NodeNotResolving message

Test plan

  • Verify commissioning with an invalid pairing code shows the CHIP SDK error in the raised exception message
  • Verify commissioning without Bluetooth configured shows the expanded guidance message
  • Verify commissioning on network with wrong PIN code includes the SDK error
  • Verify interview failure includes the SDK error
  • Verify CASE session failure includes the SDK error
  • Existing tests pass (no test changes needed — error messages are not asserted on)

🤖 Generated with Claude Code

When Matter commissioning fails, the ChipStackError (e.g. invalid
pairing code, wrong code length, network not found) was being caught
and re-raised with a generic message like "Commission with code failed
for node X" — discarding the specific error. Users had to enable
verbose logging and read tracebacks to diagnose issues.

This change appends the original error message to all commissioning-
related exceptions (NodeCommissionFailed, NodeInterviewFailed,
NodeNotResolving), making failures self-diagnosable from the UI.

Also adds a helpful hint to the Bluetooth availability error suggesting
users configure a Bluetooth adapter or use network_only mode.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@BrianHotopp
Copy link
Author

Note: we're aware this project is in maintenance mode per the README, with a rewrite underway on top of matter.js. That said, every current HAOS user is still running this Python server today, and this fix is a one-liner that makes commissioning failures self-diagnosable instead of requiring users to read source code. Seemed worth submitting even on a codebase in maintenance mode.

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