Include underlying error details in commissioning failure messages#1344
Open
BrianHotopp wants to merge 1 commit intomatter-js:mainfrom
Open
Include underlying error details in commissioning failure messages#1344BrianHotopp wants to merge 1 commit intomatter-js:mainfrom
BrianHotopp wants to merge 1 commit intomatter-js:mainfrom
Conversation
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>
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When Matter commissioning fails, the
ChipStackErrorfrom the CHIP SDK is caught and re-raised asNodeCommissionFailedwith 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:
NodeCommissionFailedincommission_with_codeandcommission_on_network— appends: {err}so the CHIP SDK error reason is visibleNodeInterviewFailedin_interview_node— same treatmentNodeNotResolvinginsdk.pyCASE session establishment — same treatmentnetwork_onlymodeMotivation
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
After
Changes
matter_server/server/device_controller.py: Include{err}inNodeCommissionFailedandNodeInterviewFailedmessages; expand Bluetooth error with actionable guidancematter_server/server/sdk.py: Include{err}inNodeNotResolvingmessageTest plan
🤖 Generated with Claude Code