Error Codes

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.

`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()
});

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

Error Codes

Error class

Error codes

Error handling

Host

Client

RPC

Debug logging

​Error class

​Error codes

​Error handling

​Host

​Client

​RPC

​Debug logging

Error class

Error codes

Error handling

Host

Client

RPC

Debug logging