Exceptions and errors

The CLI's error handling is intentionally simple: three exception families, three response styles, always exit 1.

How the application handles exceptions

Application::run() wraps the command dispatch in three catch blocks, in order:

1. 01

   `UntrustedCertificateException`.

   The server's certificate is not in the trust store. The CLI prints a structured message with the fingerprint and three follow-up commands (trust, list, skip).

2. 02

   `OpcUaException` (and subclasses).

   Any other OPC UA-side error — ConnectionException, ServiceException, SecurityException, ServiceUnsupportedException, etc. The CLI prints Error: <exception message>.

3. 03

   `RuntimeException`.

   CLI-side failures: invalid arguments, missing files, unknown flags. Same shape — Error: <message>.

UntrustedCertificateException

The most common error users see — and the only one that gets a multi-line response.

Error: Server certificate not trusted.
  Fingerprint: a1b2c3d4e5f6789012345678901234567890abcdef12345678901234567890abcd

To trust this certificate, run:
  opcua-cli trust opc.tcp://plc.local:4840

To list trusted certificates:
  opcua-cli trust:list

To skip trust validation for this command:
  opcua-cli browse ... --no-trust-policy

Three actionable follow-ups. Most users hit this once, run trust, never see it again.

For the workflow narrative, see Trust store workflow.

OpcUaException

The broad family of OPC UA-side failures, all surfaced as Error: <message> on stderr:

UntrustedCertificateException is also a subclass — caught earlier for the dedicated message.

The CLI does not distinguish between subclasses in its output. All produce Error: <message> and exit 1. To discriminate in scripts, capture stderr and grep the text:

output=$(opcua-cli browse opc.tcp://plc.local:4840 2>&1) || {
    case "$output" in
        *"Connection refused"*)    echo "down" ;;
        *"BadServiceUnsupported"*) echo "no service" ;;
        *"BadNodeIdUnknown"*)      echo "no such node" ;;
        *)                          echo "other" ;;
    esac
}

For richer error discrimination, drop down to the library directly — OpcUaException has typed subclasses your PHP code can catch.

RuntimeException

CLI-side failures fall into this bucket:

Same Error: <message> shape on stderr. Exit 1.

With --json

When --json is set, the CLI emits errors as JSON on stderr (JsonOutput::error() writes to the stderr stream). The shape is a single-key object:

{"error":"Server certificate not trusted."}

error is the only key. Additional context (the fingerprint of an untrusted certificate, follow-up commands, the bad status name) is emitted as separate error() calls — i.e. separate JSON lines on stderr:

{"error":"Error: Server certificate not trusted."}
{"error":"  Fingerprint: a1:b2:c3:d4:..."}

The CLI does not combine the fingerprint, status code, or status name into the same JSON object as error. Each error() call is wrapped independently.

To capture and parse, redirect stderr to stdout (or to a file) and feed the lines through jq:

out=$(opcua-cli read opc.tcp://plc.local:4840 i=99999 --json 2>&1 >/dev/null)
err=$(echo "$out" | jq -rs '[.[].error] | join(" / ")' 2>/dev/null)
if [ -n "$err" ]; then
    echo "Failed: $err"
    exit 1
fi

See Output formats.

Errors that don't throw

Per-item bad statuses from multi-operation services (none currently exposed at the CLI level — read and write are single-node) don't reach the exception handlers. They surface in the JSON output's Status field for read and write as a combined "Bad… (0x...)" string. The exit code is still 1 for non-Good statuses.

Sanitisation

The CLI does not sanitise messages on its own — neither the human-readable stderr output nor the JSON error line is filtered inside opcua-cli. Whatever the upstream opcua-client exception contains is forwarded verbatim.

In practice, the library's exception messages do not surface authentication tokens or password bodies, but this depends entirely on the library's own conventions. Review the error text before sharing it externally, and refer to opcua-client error handling for the upstream contract.

When you need typed errors

The CLI's text-based error contract is fine for shells, CI, operators. When your application needs typed error handling — matching on ServiceUnsupportedException to fall back to a different code path, distinguishing ConnectionException from SecurityException — embed opcua-client directly. The CLI is the operator interface; the library is the integration interface.