Timeouts and Errors

Timeouts

Timeouts are java.time.Duration values and must be at least one millisecond. The builder's timeout(...) sets the default for every operation (30 seconds when unset), and each operation can override it:

try (WinRMClient client = WinRMClient.builder("server.example.com")
        .credentials("DOMAIN\\Administrator", password)
        .timeout(Duration.ofSeconds(30))                 // client default
        .build()) {

    client.wql("SELECT * FROM Win32_NTLogEvent")
        .timeout(Duration.ofMinutes(2))                  // this query only
        .execute();
}

The timeout is a wall-clock deadline for the whole operation: it covers authentication (on the first operation), every WSMan round trip, and — for commands — the file uploads, all budgeted against the same deadline. When it elapses, the operation fails with WinRMTimeoutException^[1] and no part of it (in particular: the command itself) runs afterward.

The timeout also drives the wire-level behavior: the WSMan OperationTimeout header and the socket timeouts follow each operation's own deadline.

The exception surface

The fluent API is unchecked: every failure is a WinRMClientException^[4], with subtypes for the cases worth catching specifically:

IllegalArgumentException (invalid option values) and IllegalStateException (missing credentials at build(), or an operation on a closed client) report programming errors immediately, before anything touches the network.

Command-line exit codes

The standalone jar maps these outcomes to stable process exit codes — see the Command-Line Client^[9] manual.

See also

• Preparing the Windows Host^[10] — a symptom-to-cause table for host-side causes: WinRM disabled, a closed firewall, UAC token filtering, and missing WMI rights
• Authentication^[11] — how authentication failures are reported