nexus
Core guides

Errors And Timeouts

Handle connection, service-acquisition, and call failures at their own boundaries.

Nexus separates acquiring a connection, getting a service, and executing a call. Handle failure at the boundary where your application can make a decision.

BoundaryThrow-styleResult-style
Connection acquisitionawait app.connect(options)await app.safeConnect(options)
Service acquisitionconnection.get(Token)connection.safeGet(Token)
Remote operationawait service.method()await Nexus.safeCall(service.method())

Safe async methods return native Promises of better-result Results. Await first, then use isErr() or isOk() to narrow the result.

Handle Each Boundary

import { Nexus } from "@nexus-js/core";
import { DocumentToken } from "./shared";

async function summarize() {
  const connected = await app.safeConnect({ target });
  if (connected.isErr()) {
    console.error("Connection:", connected.error.code);
    return;
  }

  const acquired = connected.value.safeGet(DocumentToken);
  if (acquired.isErr()) {
    console.error("Service:", acquired.error.code);
    return;
  }

  const called = await Nexus.safeCall(acquired.value.summarize("intro"));
  if (called.isErr()) console.error("Call:", called.error.code);
  else console.log(called.value);
}

app and target come from your runtime setup. safeGet does not make the returned proxy’s methods return Results. safeCall consumes one Nexus operation; it does not accept arbitrary Promises or arrays and does not resend the call.

If a service itself returns a business Result, the outer safeCall Result reports RPC success and the inner value reports the business outcome.

Distinguish Business And Communication Failures

An exception thrown by the remote business method becomes NexusRemoteError with code E_REMOTE_EXCEPTION. Disconnect, authorization, unavailable resources, and protocol failures keep their framework classifications. Local processing after awaiting the result can still throw a local error.

Use stable error.code values for cross-context or duplicate-package handling. Error context and cause supply diagnostic details. See the error reference.

Time Budgets

OperationDefaultStarts
Active connection acquisition30 secondsAt API invocation, including local initialization
Passive single connectionNo limit unless suppliedAt API invocation
Connection collection acquisition30 secondsAt API invocation; no future-member wait for snapshots
Remote call5 secondsAt first consumption

timeout and callTimeout must be positive finite milliseconds. Zero, negative numbers, NaN, and Infinity are invalid. A multi-target acquisition shares one budget across its targets.

Set a local runtime default before bootstrap, or override it for one service handle:

app.configure({ ...runtimeConfig, callTimeout: 10_000 });

const documents = connection.get(DocumentToken, { callTimeout: 30_000 });

runtimeConfig includes the endpoint setup. An override does not modify the shared Connection. Refs returned from that handle inherit its budget; callbacks received by the peer use that peer’s local default.

Cancel A Connection Wait

const controller = new AbortController();
const pending = app.safeConnect({ target, signal: controller.signal });
controller.abort();
const result = await pending;

The signal controls this acquisition wait. It does not close a shared session, cancel another caller’s acquisition, or control later RPC calls.

Decide Whether To Retry

A call timeout ends local waiting; it does not prove that the remote operation never ran or that its effects were rolled back. Retry only when the business operation makes that safe, for example with an application idempotency key.

After disconnect, acquire a new connection and fresh service or resource handles. Old handles never silently retarget. Business exceptions alone do not disconnect the session. See Connection lifecycle.

Edit this page on GitHub