opcua-doctor
Find out why an OPC UA connection fails, and what to do about it.
OPC UA servers refuse connections with codes like BadSecurityChecksFailed and, on purpose, do not say more. opcua-doctor walks through the connection step by step (address, endpoints, certificates, trust, login) and stops at the first thing that is wrong, with the cause and the fix in plain words.
$ opcua-doctor opc.tcp://192.168.0.10:4840 --cert client.der --key client.pem --user operator
address
[ OK ] 192.168.0.10:4840 is reachable
endpoints
Basic256Sha256 / SignAndEncrypt
login: UserName; address: opc.tcp://plant-pc:4840/secure/
server certificate
[ OK ] server certificate is valid until 2027-11-12 (364 days)
server certificate application URI: urn:test:server
[WARN] '192.168.0.10' is not listed in the server certificate
it lists: plant-pc
-> Strict clients refuse this (BadCertificateHostNameInvalid). Connect with a listed name, or recreate the server certificate.
client certificate
[ OK ] client certificate is valid until 2027-11-12 (364 days)
client certificate application URI: urn:test:client
[ OK ] private key belongs to the certificate
choice
[ OK ] trying Basic256Sha256 / SignAndEncrypt with user name login
session
[FAIL] refused: BadCertificateUntrusted
The server does not trust the client certificate.
-> Add the client certificate (.der) to the server's trust list. On many servers it is waiting in a 'rejected' folder after the first attempt.
Connection does not work. 1 problem(s), 1 warning(s).
Output of a real run against the test server in this repo; address and host name changed for the example.
Install
With internet:
pip install https://github.com/sulemanali5760/opcua-doctor/releases/download/v0.1.1/opcua_doctor-0.1.1-py3-none-any.whl
Without internet (a plant PC, a commissioning laptop on the machine network): download the offline bundle for your system from the latest release, carry it over on a USB stick, unzip it and run inside the folder:
python -m pip install --no-index --find-links . opcua-doctor
The bundle holds this tool and every package it needs; nothing is downloaded. Each bundle is installed in a clean environment and started once before it is published. Python 3.11 or newer. Not on PyPI yet.
Use
opcua-doctor opc.tcp://host:4840 # what does the server offer, can I get in without security
opcua-doctor opc.tcp://host:4840 --cert c.der --key c.pem # encrypted, anonymous
opcua-doctor opc.tcp://host:4840 --cert c.der --key c.pem --user operator
opcua-doctor opc.tcp://host:4840 --policy Basic256Sha256 --mode Sign --cert c.der --key c.pem
opcua-doctor opc.tcp://host:4840 --json # for scripts and CI
The password is read from OPCUA_PASSWORD or asked for; it is never an argument. Exit code 1 if the connection does not work.
From Python:
from opcua_doctor import diagnose
findings = await diagnose("opc.tcp://host:4840", cert="c.der", key="c.pem")
What it checks
| Step | Finds |
|---|---|
| address | not an opc.tcp URL, name does not resolve, nothing answers on the port |
| endpoints | which security policies, modes and login types the server offers; a server that advertises a host name your machine cannot resolve; only deprecated policies |
| server certificate | expired or not yet valid, application URI mismatch, host name not in the certificate, weak key, SHA-1 signature |
| client certificate | unreadable file, expired or not yet valid, no application URI, URI differs from the one the client uses, key does not belong to the certificate |
| choice | server needs encryption and you gave no certificate, policy or mode not offered, anonymous not allowed, user name login not offered |
| session | connects for real and translates the refusal: 23 status codes (BadSecurityChecksFailed, BadCertificateUntrusted, BadCertificateUriInvalid, BadUserAccessDenied, BadIdentityTokenRejected, BadTooManySessions, …) into cause and fix; clock difference between both machines |
It reads two standard nodes (server time and namespace table) and nothing else. It never writes to the server.
Tested
Every test breaks a connection in one specific way against a real OPC UA server started in the test, and expects the doctor to name that cause: unreachable port, unresolvable name, server without the requested policy, encrypted-only server without certificate, login required, untrusted client certificate, wrong password. Certificate problems (expired, not yet valid, no URI, URI mismatch, wrong key) are tested with certificates generated for the purpose.
Limits
- Tested against one server stack (the
asyncuaserver). Siemens, Beckhoff, B&R, Kepware and others word and order their refusals differently; the status codes are standard, but which one a server picks for a given cause is not. Reports from real controllers are welcome as issues. - A server that hides the reason stays hidden.
BadSecurityChecksFailedcan have several causes; the doctor lists them in order of likelihood, it cannot see into the server. - RSA certificates and user name login only. No ECC policies, no certificate or token-based user identity.
- It does not change anything. It will not create certificates or move them into trust lists for you.
- The explanations follow the status-code definitions in OPC 10000-4 and OPC 10000-6; the "most often" hints are the author's reading of public issue trackers and forums, not a statistic.
Why
BadSecurityChecksFailed alone appears in over a hundred GitHub issues across OPC UA projects, and the Python OPC UA library asyncua has about 95 issues on security and 79 on certificates (counted 12 Nov 2026). The answers are almost always one of the checks above.
Licence
MIT
Metadata
Release files for opcua-doctor 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| opcua_doctor-0.1.1.tar.gz | 17.9 kB | With provenance | Details for opcua_doctor-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| opcua_doctor-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for opcua_doctor-0.1.1-py3-none-any.whl |
Total release size: 31.8 kB
Release files / opcua_doctor-0.1.1.tar.gz
| Download URL | opcua_doctor-0.1.1.tar.gz |
|---|---|
| Size | 17.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c3cf3c4a6f206d63fa4f2119baafd19a7cab6d260573cec3238a5f73b31881a
|
|
BLAKE2b-256 checksum How to use checksums |
9074d0c8facd275586274dfd6360b7ccd89ec481e485d5a026cdd008d36b85ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / opcua_doctor-0.1.1-py3-none-any.whl
| Download URL | opcua_doctor-0.1.1-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f698838b4cdae00a77f4b8b449e9c155132bb6fa54ac59e7f0e532415d03e51
|
|
BLAKE2b-256 checksum How to use checksums |
0c143e321b7e34b316a7d213e257b2e40948b3bba091a74e106f220dd332da0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for opcua-doctor 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for opcua_doctor-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.