Troubleshooting

Common Crosslink failures, what they usually mean, and how to debug them without weakening the security model.

Troubleshooting

When something fails, start by locating the layer that failed:

1. Pairing and trust establishment.
2. Transport reachability.
3. Capability authorization.
4. Storage and key handling.
5. App-specific RPC logic.

That order matters because the same symptom can be produced by very different causes. A refused connection is not the same as a revoked device, and a bad SAS is not the same as a relay outage.

Pairing issues

Pairing code expired

Symptom: PAIRING_CODE_EXPIRED

Cause: Pairing codes have a 2-minute TTL and are single-use.

Fix:

• Generate a new pairing code.
• Complete pairing within 2 minutes.
• If you are testing a slow flow, shorten the path between scanning the QR and approving the device.

Pairing code already used

Symptom: PAIRING_CODE_USED

Cause: The code was consumed by another client or by a previous attempt.

Fix:

• Generate a fresh code.
• Do not reuse a QR after the host has already completed pairing.
• If the client auto-retried, clear the stale state before trying again.

Fingerprint mismatch

Symptom: FINGERPRINT_MISMATCH or “host fingerprint does not match”

Cause: The host fingerprint in the QR does not match the host the client actually reached.

Security warning: Treat this as a potential MITM or stale-QR event until proven otherwise.

Fix:

• Verify that the desktop host is the one you intended to pair with.
• Regenerate the QR from the current host process.
• Check whether a signaling or tunnel endpoint was swapped out underneath you.

Pairing rejected by host

Symptom: PAIRING_FAILED

Cause: The host’s approval callback returned false, timed out, or was never surfaced to the user.

Fix:

• Check the host logs for the rejection reason.
• Confirm the requested capabilities are allowed by policy.
• Make sure your approval UI is actually reaching the human who needs to answer.

Connection issues

Connection refused

Symptom: CONNECTION_FAILED

Fix:

1. Check the services that should be running:

   curl http://127.0.0.1:8081/health
   curl http://127.0.0.1:8082/health
   

2. Confirm that the host and client are using the same signaling and relay URLs.

3. Confirm that the host is binding to the right interface for the mode you selected.

4. Check whether a firewall or another local process already owns the port.

Connection timeout

Symptom: CONNECTION_TIMEOUT

Fix:

1. Check basic network connectivity first.
2. Increase dialTimeoutMs if the route is legitimately slow.
3. Confirm the route kind is valid for the network you are on.
4. If a relay is configured, verify that the relay is reachable and not just the signaling service.

Relay unavailable

Symptom: RELAY_UNAVAILABLE

Fix:

1. Check the relay URL and port.
2. Check whether the relay service is actually running.
3. Confirm the relay token and any client token are correct.
4. If the devices are on the same network, try LAN first to isolate the issue.

Signaling unavailable

Symptom: SIGNALING_UNAVAILABLE

Fix:

1. Check the signaling URL and port.
2. Confirm the signaling service is running.
3. Verify that the WebSocket upgrade is reaching the service.
4. If you are using per-machine dev tokens, make sure the host and service are reading the same .crosslink-data location.

RPC issues

Method not found

Symptom: METHOD_NOT_FOUND

Fix:

1. Check the method name.
2. Confirm the host exposes that method.
3. Confirm the client is connected to the intended host, not a stale tab or old session.

Capability denied

Symptom: CAPABILITY_DENIED

Fix:

1. Check whether the capability was requested during pairing.
2. Check whether the host granted it.
3. Re-pair with the required capability if the policy was too strict.
4. If the capability should have been allowed, inspect the policy and approval hook on the host.

RPC timeout

Symptom: TIMEOUT

Fix:

1. Check whether the host is responsive.
2. Look for a slow handler or a queueing bug.
3. Increase the timeout only after confirming the handler is actually healthy.

Storage issues

Secret storage unavailable

Symptom: STORAGE_ERROR

Fix:

1. Check OS keychain availability first.
2. If you are using Electron, confirm safeStorage is available.
3. If you deliberately allow it, set CROSSLINK_SECRET_KEY so the encrypted-file fallback has a fixed passphrase.
4. Use allowPlaintextFallback: true only for development and only when you understand the risk.

Browser storage not encrypted

Symptom: Warning such as “identity seed is stored in the clear”

Cause: WebCrypto or IndexedDB was unavailable, or the page is not in a secure context.

Fix:

1. Serve the page from HTTPS or localhost.
2. Confirm the browser actually supports the needed APIs.
3. Prefer CrosslinkClient.create() over the plain constructor when you need the secure storage path.

Transport issues

WebRTC not connecting

Symptom: The connection falls back to relay.

Fix:

1. Check ICE configuration and any STUN/TURN dependencies.
2. Confirm the direct path is actually available between the peers.
3. Treat relay fallback as a valid outcome unless you specifically require a direct DataChannel.

LAN not working

Symptom: Devices cannot discover or reach one another on the local network.

Fix:

1. Confirm both devices are on the same network segment.
2. Check the host’s LAN listener port and firewall rules.
3. Confirm the host is not bound only to loopback if the phone needs to reach it.
4. If you are testing on one machine, loopback is fine; if you are testing across devices, it is not.

Remote access not working

Symptom: networkMode: "remote" fails startup or the QR does not contain a public route.

Fix:

1. Run npm run check:remote or node scripts/check-remote-access.mjs <port>.
2. Confirm the router actually supports PCP, NAT-PMP, or UPnP IGD.
3. Check for carrier-grade NAT or a double-NAT setup.
4. If you configured a manual port forward, make sure the public host and external port match reality.

Debug logging

Use structured logs to debug, not ad-hoc string concatenation. The logger must support the full interface from @crosslink/core.

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

const server = createCrosslinkServer({
  application: { id: "com.example.notes", name: "Notes" },
  logger: consoleLogger({ level: "debug" })
});

When you are reading logs:

• Start with the event name and the transport or capability involved.
• Look for redacted reasons, not raw request objects.
• Do not paste secrets, tokens, seeds, or private keys into logs just to “see what is happening”.
• If the logger is too quiet, raise the level before you add more instrumentation.

Practical recovery loop

If you are stuck, use this sequence:

1. Restart the host and re-check the advertised endpoints.
2. Regenerate the pairing QR.
3. Verify the SAS digits on both devices.
4. If the problem is network reachability, run the remote-access check.
5. If the problem is authorization, inspect the capability policy and approval hook.
6. If the problem is storage, verify the keychain or encrypted-file backend before looking elsewhere.