Error Codes

All Crosslink error codes and how to handle them

Error class

All Crosslink protocol errors are instances of CrosslinkError.

class CrosslinkError extends Error {
  readonly code: string;
  readonly data?: unknown;
  toWire(): { code: string; message: string; data?: unknown };
}

code is one of the values below. These travel on the wire as lowercase, underscore-separated strings and are stable — new codes may be added, existing ones are never repurposed.

---

Error codes

ErrorCodes key	Wire value	Description
PARSE_ERROR	parse_error	Payload was not valid UTF-8 / JSON
INVALID_MESSAGE	invalid_message	Message failed structural validation
VERSION_UNSUPPORTED	version_unsupported	No mutually supported protocol version
UNAUTHORIZED	unauthorized	Signature or trust check failed
CAPABILITY_DENIED	capability_denied	Device lacks the required capability
METHOD_NOT_FOUND	method_not_found	RPC method doesn’t exist
VALIDATION_FAILED	validation_failed	Input failed schema/custom validation
PAYLOAD_TOO_LARGE	payload_too_large	Message exceeds the session frame limit
RATE_LIMITED	rate_limited	Too many requests
DEVICE_REVOKED	device_revoked	This device’s access was revoked
SESSION_EXPIRED	session_expired	Handshake timestamp outside the allowed clock skew
PAIRING_EXPIRED	pairing_expired	Pairing code/session expired
PAIRING_INVALID	pairing_invalid	Pairing frame rejected (wrong code, cancelled, mismatched nonce)
HOST_OFFLINE	host_offline	Host not reachable
TIMEOUT	timeout	RPC call timed out
CANCELLED	cancelled	Request was cancelled
INTERNAL	internal	Unclassified internal error
NOT_CONNECTED	not_connected	No live session to send on
PEER_LOST	peer_lost	Transport died while a request was in flight
GRANT_EXPIRED	grant_expired	Capability grant lapsed and must be renewed
CONSENT_DENIED	consent_denied	Host user declined a per-use confirmation prompt
CONSENT_TIMEOUT	consent_timeout	Host could not obtain per-use confirmation in time
POLICY_DENIED	policy_denied	Host permission policy forbids this, independent of the grant

CrosslinkError.isInternal(code) is true for internal, parse_error, and invalid_message — codes that must never leak raw detail across the wire.

Fingerprint mismatches during pairing (client.pairFromQr) and a few pairing-flow guard checks throw a plain Error rather than a CrosslinkError, so they have no code property — check the message text instead.

---

Error handling

Host

try {
  await server.start();
} catch (err) {
  console.error("Failed to start:", err);
}

Client

try {
  await client.pairFromQr(uri, ["app.control"]);
} catch (err) {
  if (err.message?.includes("fingerprint")) {
    console.error("SECURITY: host fingerprint mismatch -- possible MITM");
  } else if (err.code === "pairing_invalid") {
    console.error("Pairing rejected or cancelled");
  } else {
    console.error("Pairing error:", err);
  }
}

RPC

try {
  await rpc.call("app.status");
} catch (err) {
  if (err.code === "capability_denied") {
    console.error("Missing capability");
  } else if (err.code === "method_not_found") {
    console.error("Method not exposed by host");
  } else {
    console.error("RPC error:", err);
  }
}

---

Debug logging

Enable debug logging to trace errors. A logger must implement the full Logger interface (trace, debug, info, warn, error, child, isEnabled) — use consoleLogger() from @crosslink/core rather than a partial object literal:

import { consoleLogger } from "@crosslink/core";
import { createCrosslinkServer } from "@crosslink/sdk-node";

const server = createCrosslinkServer({
  // ...
  logger: consoleLogger()
});