Zigbee2MQTT / Troubleshooting
Zigbee2MQTT Cannot Open the Adapter Serial Port
Separate a missing USB device from an incorrect serial path, runtime mapping, access denial or a competing coordinator owner.
First locate the failure stage. The documented discovery message includes No valid USB adapter found; Cannot lock port is a different access problem. Neither makes every coordinator startup failure a missing-device case.[1]
Applicability
- Products
- Zigbee2MQTT
- Scope
- For a local USB coordinator on Linux when current Zigbee2MQTT logs show discovery or serial-open failure. Covers native Linux and documented Docker runtime checks. Home Assistant is environment/ownership context only. Excludes network coordinators, MQTT, pairing, RF issues, unavailable end devices and errors after successful serial opening. Add-on-specific corrections are a packaging-owner handoff.[1][2]
- Last verified
Symptoms
- The current startup or reconnect log points to USB discovery, a nonexistent configured device, denied access or a locked port before normal coordinator operation.[1]
Quick diagnosis
Gather current evidence before choosing a branch. Unknown observations do not establish a failed component.
Read the current failure, not an old notification
Record the time and error stage from existing logs. If serial opening succeeded and a protocol handshake failed later, leave this intent. Keep identifiers and complete logs private.[1]
Inspect existing stable device paths
On the Linux host, list existing by-id entries and identify the actual adapter, including the correct interface if there is more than one. A missing directory does not alone prove the USB device is absent; consult OS hardware evidence.[2]
ls -l /dev/serial/by-idIdentify the runtime before comparing paths
Record native Linux, Docker or Home Assistant add-on packaging. In Docker, host and container device paths may differ. Do not paste Docker configuration flags into an add-on UI.[3][5]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Safe diagnostic guidanceIs this a local USB discovery or open failure?
Use current logs on Linux. Successful serial opening followed by a later error is outside this intent.[1]
Read the complete diagnostic tree without using the controls
- Is this a local USB discovery or open failure?
Use current logs on Linux. Successful serial opening followed by a later error is outside this intent.[1]
- Yes, USB discovery/open stage → Is the expected adapter visible to the host OS?
- No, another stage or environment → Use the actual failure stage's documentation
- Is the expected adapter visible to the host OS?
Use actual hardware identity, not only a guessed serial filename.[2][4]
- Yes, the expected device is visible → Which path comparison applies?
- No, the expected device is absent → Investigate OS-level device visibility
- Host visibility is unknown → Preserve an adapter-access evidence packet
- Which path comparison applies?
Compare actual and configured port; in Docker compare both sides of the device mapping.[2][3]
- Existing path and runtime mapping match → Is there actual runtime permission-denied evidence?
- Configured serial path is wrong → Review the configured serial path
- Runtime device mapping is missing or wrong → Review the runtime device mapping
- Packaging or path is uncertain → Preserve an adapter-access evidence packet
- Is there actual runtime permission-denied evidence?
Distinguish an existing inaccessible device from a missing device path.[1][3]
- Yes, runtime access is denied → Review least-privilege device access
- No denial is established → Is a competing coordinator owner established?
- Access evidence is unknown → Preserve an adapter-access evidence packet
- Is a competing coordinator owner established?
Identify the process/integration actually using this adapter before planning interruption.[4][1]
- Yes, another owner is confirmed → Plan exclusive coordinator ownership
- No competing owner is established → Does exact hardware documentation show a configuration mismatch?
- Ownership is unknown → Preserve an adapter-access evidence packet
- Does exact hardware documentation show a configuration mismatch?
Compare the adapter family; do not treat a later handshake failure as proof of a missing port.[2]
- Yes, an adapter-family mismatch is evidenced → Request exact adapter configuration review
- The port opened and the failure is later → Use the actual failure stage's documentation
- No supported mismatch or still uncertain → Preserve an adapter-access evidence packet
- Use the actual failure stage's documentation
Record the stage, runtime and error. MQTT, pairing, RF and post-open protocol failures need separate diagnosis; no reset is warranted by this tree.[1]
- Investigate OS-level device visibility
Send expected identity and host observations to the hardware/host owner; preserve the current coordinator configuration.[2][4]
- Review the configured serial path
Provide the observed path and configured value. Request a bounded correction to an existing appropriate path, not a guessed tty number.[2]
- Review the runtime device mapping
Give the deployment owner both device paths and packaging details. Host access does not establish container access.[3][5]
- Review least-privilege device access
Send current denial evidence and runtime identity to the owner. Do not make the device world-writable.[3]
- Plan exclusive coordinator ownership
Name the established competing owner. Any service stop or ownership switch requires the disruptive-change prerequisites below.[4]
- Request exact adapter configuration review
Use the identified hardware's official instructions. No guessed adapter setting or firmware action is provided.[2]
- Preserve an adapter-access evidence packet
Keep current error stage, device identity, paths, mapping and access observations. Ask the packaging/adapter owner for the missing evidence.[2][3]
Detailed diagnosis
1. Establish host visibility
Compare the expected coordinator identity with current OS hardware evidence. Do not interpret the absence of a guessed ttyUSB/ttyACM number as physical failure.[2][4]
2. Compare actual and configured paths
Read the configured serial port and compare it with the existing adapter path. A stable by-id entry is useful only when it exists and refers to this adapter; do not invent a replacement path.[2]
3. Compare host and runtime access
For Docker, inspect the deployment's source device and container destination. The application must use the runtime destination; host visibility alone is insufficient. The documented container setup also describes read-only udev data for autodetection.[3]
4. Separate denial from absence
Inspect the device ownership and the actual runtime identity with the deployment owner. Require a current access-denied observation; a missing path is not proven permission denial.[3][1]
5. Identify any competing coordinator owner
A locked-port error warrants checking which process owns the adapter. Home Assistant documents that one coordinator cannot be shared with another controlling application. Do not stop ZHA merely because it is installed.[4][1]
6. Check the exact adapter family
Compare the configured adapter selection with the official documentation for the exact hardware. Do not guess a value or flash firmware. Successful opening followed by another failure requires a different investigation.[2]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
Path or runtime mapping differs
An OS-visible device and the path available to the process are separate observations.[3]
How to check: Compare the host entry, mapping destination and configured serial port.[2][3]
Access is denied or the coordinator is occupied
Permission evidence and an existing owner distinguish two different access boundaries.[1][4]
How to check: Inspect the current runtime identity and actual ownership, without broadening access.[3]
Configuration needs hardware-specific review
The adapter family is not determined by an arbitrary example configuration.[2]
How to check: Identify the exact hardware and its official adapter instructions.[2]
Next actions and procedure boundaries
Missing device: host-owner investigation
Provide expected identity and current hardware evidence. Ask the host owner to establish visibility; do not reset the coordinator or unplug devices as a generic remote test.[2][4]
Path or mapping mismatch: deployment review
Record the actual versus configured path and, for Docker, both mapping sides. The deployment owner should plan only the evidenced correction using the applicable packaging instructions.[2][3][5]
Permission or ownership mismatch: bounded review
Provide the runtime identity, exact denial or established competing process. Request least-privilege access or an explicit choice of coordinator owner, not blanket permission changes.[3][4]
Before a coordinator configuration or owner change
Planning boundary only: a restart or ownership switch can interrupt automations. An authorized Home Assistant/Zigbee operator must agree on the intended owner and affected services before any separate action.[4]
Before changing anything
- Risk
- Restarting or stopping the controlling application can interrupt Zigbee automations.[4]
- Safer check
- First establish a real path, access or ownership mismatch from current evidence.[3][4]
- Expected result
- A proposed change should allow the intended runtime to open the intended adapter without a competing owner; subsequent protocol errors are a separate diagnosis.[2][4]
- Backup / recovery access
- Before work, preserve the existing deployment configuration and available coordinator backups using that stack's supported process. Identify the responsible operator and affected automations.[4]
- Rollback
- Do not promise a universal coordinator rollback. The owner must verify restoration of the previous runtime/configuration before changing it; no reset, migration or firmware procedure is supplied here.[4]
Adapter mismatch or unresolved evidence
Give the operator the exact adapter, runtime, current error stage and sanitized comparisons. Consult model-specific documentation; do not invent an adapter value. After-open failures leave this serial-access page.[2][1]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-05. Reachability and automated validation do not replace editorial verification of each claim.
- Zigbee2MQTT fails to start/crashes runtime
Zigbee2MQTT · Tier A · accessed 2026-09-05 - Adapter settings
Zigbee2MQTT · Tier A · accessed 2026-09-05 - Docker
Zigbee2MQTT · Tier A · accessed 2026-09-05 - Zigbee Home Automation
Home Assistant · Tier A · accessed 2026-09-05 - Home Assistant addon
Zigbee2MQTT · Tier A · accessed 2026-09-05