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 request can override it (uploadFile(...) and downloadFile(...) always use the client's):

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 (for a file download: the whole transfer), all budgeted against the same deadline. When it elapses, the operation fails with WinRMTimeoutException^[1] and stops: a command not started yet is never started, and one still running is terminated.

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

Retrying transient connection failures

By default there is no retry: a transient network failure — a dropped connection, a DNS hiccup, a momentarily unreachable host — fails the operation immediately. The opt-in retries(...) builder setting rides out such failures, which long-running monitoring and automation workloads usually want:

WinRMClient client = WinRMClient.builder("server.example.com")
    .credentials("DOMAIN\\Administrator", password)
    .retries(2, Duration.ofSeconds(5))   // up to 2 retries, pausing 5 s before each
    .build();

The policy is deliberately narrow, to preserve at-most-once execution for non-idempotent commands: a WSMan round trip is retried only when it failed to establish and authenticate the connection — TCP connect, DNS resolution, the TLS handshake, or a transport error during the authentication handshake — because there the request provably never reached the server. WQL queries get no broader surface even though they are idempotent: re-issuing a WS-Enumeration Pull whose response was lost could skip or duplicate rows.

The policy is connection-scoped: it applies to every round trip of every operation on the client, including reconnections in the middle of one (WinRM connections are re-established transparently when the server drops an idle one). What is never retried:

• a request that reached the wire — a command that may have started, a query that may be executing;
• credential rejections (WinRMAuthenticationException^[5]);
• WSMan faults (WinRMFaultException^[6]), except the refusals that prove a command never ran, whatever the policy: a shell the host reaped and, on Windows Server 2008 R2, the operation quota are retried once in a new shell (see Shell reuse^[7]), and file transfers^[8] and remote file operations^[4] then retry a quota refusal up to 4 more times, with escalating delays (5/10/15/20 s) bounded by their timeout.

Retries stay inside each operation's wall-clock deadline: when the timeout elapses mid-pause, the operation fails with WinRMTimeoutException^[1] exactly as it would without a retry policy. For the streaming terminals (whose timeout is an inactivity timeout with no overall deadline), each connection attempt is bounded by that timeout, so a retried reconnection can extend the tolerated silence accordingly.

Users migrating from winrm4j: retries(1, Duration.ofSeconds(5)) is the closest equivalent of its default failureRetryPolicy (one retry, 5-second pause).

The exception surface

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

IllegalArgumentException (invalid option values) and IllegalStateException (e.g. 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^[12] manual.

See also

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