matlab/matlab-agentic-toolkit / skills-catalog/test-and-measurement/matlab-use-opcua-client
matlab-use-opcua-client
VerifiedDiscover OPC UA servers, connect MATLAB clients, and browse/navigate server nodes using opcuaserverinfo, the Local Discovery Service (LDS), opcua, connect, setSecurityModel, certificate-trust functions, findNodeById, opcuanode, and Namespace/Children traversal. Use when finding OPC UA servers on the network, querying endpoints and security policies, connecting to a server, authenticating with username/password or certificates, configuring security modes, handling certificate-trust or hostname-mismatch errors, troubleshooting failed connections or empty discovery, inspecting an OPC UA certificate (.der/.pem), browsing an address space, finding nodes by name or NodeId, navigating node hierarchies, invoking method nodes, or batch-processing large namespaces. Trigger on: opcuaserverinfo, LDS, opcua, opc.ua.Client, setSecurityModel, opc.ua.trustServerCertificate, OPC UA certificate, findNodeById, opcuanode, browse OPC UA, find node, OPC UA namespace, OPC UA method node, Industrial Communication Toolbox.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.1 KB |
| manifest.yaml | config | 493 B |
| references/certificate-trust-workflows.md | markdown | 5.7 KB |
| references/common-mistakes.md | markdown | 4.3 KB |
| references/lds-setup-and-troubleshooting.md | markdown | 4.8 KB |
| references/node-functions-reference.md | markdown | 7.2 KB |
| references/node-navigation.md | markdown | 7.7 KB |
| references/troubleshooting-connection-errors.md | markdown | 5.6 KB |
| scripts/inspectOpcUaCertificate.m | other | 7.0 KB |
references/troubleshooting-connection-errors.md
View on GitHub# Troubleshooting OPC UA Connection Errors
Diagnose and resolve OPC UA client connection failures in MATLAB.
## Error-to-Fix Quick Reference
| Error Message | Root Cause | Fix |
|---------------|-----------|-----|
| "Server certificate not trusted" | Server cert not in MATLAB trust store | `opc.ua.trustServerCertificate(path)` (R2026a+) or manual copy |
| "Client certificate rejected" | MATLAB cert not in server trust store | `opc.ua.exportClientCertificate` then trust on server |
| "BadIdentityTokenRejected" | Wrong credentials or auth type not enabled | Check `uaClient.UserAuthTypes`; verify credentials |
| "BadSecurityChecksFailed" | Certificate compliance issue or policy mismatch | Inspect cert fields; check server logs |
| "Hostname mismatch" warning | Endpoint URL hostname differs from input | `UseDiscoveryHostname=true` (R2025a+) |
| "Unable to connect to endpoint" | Server down, wrong URL, or firewall | Verify server is running; check URL and port |
| "BadSecurityPolicyRejected" | Requested policy not supported by server | Query `uaClient.Endpoints` for available policies |
| "Connection timeout" | Network issue or server overloaded | Increase `uaClient.Timeout`; check network |
## Diagnostic Workflow
### Step 1: Verify server is reachable
```matlab
serverUrl = "opc.tcp://hostname:port/path";
uaClient = opcua(serverUrl);
fprintf("Status: %s\n", uaClient.Status);
fprintf("Endpoints found: %d\n", numel(uaClient.Endpoints));
```
If `opcua` itself fails, the server is unreachable — check URL, network,
and firewall before investigating security.
### Step 2: Check available security and auth types
```matlab
fprintf("Security Mode: %s\n", string(uaClient.MessageSecurityMode));
fprintf("Channel Policy: %s\n", string(uaClient.ChannelSecurityPolicy));
fprintf("Auth Types: %s\n", strjoin(string(uaClient.UserAuthTypes), ", "));
```
### Step 3: Attempt connection with timestamp
```matlab
attemptTime = datetime("now", Format="yyyy-MM-dd HH:mm:ss.SSS");
fprintf("Attempt at: %s\n", string(attemptTime));
try
connect(uaClient);
fprintf("Connected successfully.\n");
catch ME
fprintf("Failed: %s\n", ME.message);
fprintf("Search server logs near: %s\n", string(attemptTime));
end
```
### Step 4: Check server logs
Use the recorded timestamp to search server logs for the rejection
reason. The server-side message is almost always more specific than
MATLAB's client-side error.
## Server Log Locations
| Server Implementation | Log Location |
|----------------------|-------------|
| Prosys Simulation Server | `~/.prosysopc/prosys-opc-ua-simulation-server/logs/` |
| Prosys (alternative) | `C:/ProgramData/Prosys OPC UA Simulation Server/logs/` |
| Unified Automation UaGateway | `C:/ProgramData/UnifiedAutomation/UaGateway/logs/` |
| Unified Automation UaCPPServer | `C:/ProgramData/UnifiedAutomation/UaCPPServer/logs/` |
| Kepware KEPServerEX | `C:/ProgramData/Kepware/KEPServerEX/V6/Logs/` |
| open62541 (Linux) | stdout/stderr or `journalctl -u <service>` |
| Node-OPC UA | Console output (set `DEBUG=opcua*`) |
## Server Log Patterns and Fixes
| Log Pattern | Meaning | MATLAB Fix |
|-------------|---------|-----------|
| "Certificate not in trust list" | Server doesn't trust MATLAB's client cert | Export client cert, add to server's trusted store |
| "ApplicationUri mismatch" | Cert URI doesn't match session URI | Regenerate MATLAB cert: delete `fullfile(prefdir, "OPC UA", "pki", "own")` |
| "Security policy not supported" | Requested policy disabled on server | Use `setSecurityModel` with a supported policy |
| "Signature verification failed" | Corrupted key material | Delete `fullfile(prefdir, "OPC UA", "pki")` and reconnect |
| "Certificate expired" | Certificate validity period exceeded | Regenerate cert; check system clock sync |
| "User token rejected" | Bad credentials or auth type disabled | Verify credentials; check server user config |
## MATLAB OPC UA PKI Folder Structure
MATLAB stores its OPC UA client certificates and trust data in:
```
<prefdir>/OPC UA/pki/
├── own/
│ ├── certs/ <- MATLAB's client application certificates
│ └── private/ <- MATLAB's client private keys
├── trusted/
│ └── certs/ <- Server certs MATLAB trusts
└── rejected/
└── certs/ <- Server certs MATLAB has rejected
```
Find the path with: `fullfile(prefdir, "OPC UA", "pki")`
## Common Debugging Scenarios
### Anonymous auth disabled but no credentials provided
```matlab
uaClient = opcua(serverUrl);
% Check what's available
disp(uaClient.UserAuthTypes);
% If Anonymous is not listed, must provide credentials:
connect(uaClient, "username", "password");
```
### Server only supports a specific security policy
```matlab
uaClient = opcua(serverUrl);
% Inspect available endpoints
for k = 1:numel(uaClient.Endpoints)
ep = uaClient.Endpoints(k);
fprintf("Endpoint %d: %s / %s\n", k, ...
string(ep.MessageSecurityMode), string(ep.ChannelSecurityPolicy));
end
% Use a supported combination
setSecurityModel(uaClient, "Sign", "Basic256Sha256");
connect(uaClient);
```
### Certificate regeneration (nuclear option)
If nothing else works and you suspect corrupted MATLAB PKI state:
```matlab
pkiDir = fullfile(prefdir, "OPC UA", "pki");
fprintf("Removing PKI folder: %s\n", pkiDir);
rmdir(pkiDir, "s");
% MATLAB will regenerate certificates on next connection attempt
uaClient = opcua(serverUrl);
connect(uaClient);
```
This deletes all stored certificates and keys. MATLAB will generate
fresh ones on the next secure connection attempt. You will need to
re-trust the new client certificate on the server side.
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |