Errors

Every command that fails rejects with a WaylocateError. The code is the part to branch on; the message is for logs and bug reports, and its wording is not part of the contract.

Handling

import { WaylocateError } from "@waylocate/embed";

try {
  await map.selection.setRoom("muntz-hall/999");
} catch (error) {
  if (error instanceof WaylocateError && error.code === "REF_NOT_FOUND") {
    showNotFound();
  } else {
    throw error;
  }
}

isWaylocateError(value) is exported as an alternative to instanceof, which is useful when more than one copy of the package could be present in a bundle.

Codes

Code	Meaning	Usual cause
REF_NOT_FOUND	The reference does not resolve in this campus	A typo, or a slug from a different campus
NOT_READY	The map could not act yet	A command sent before the campus loaded, or fitTo("route") with no route
UNSUPPORTED	This map build does not have that command	An SDK newer than the deployed map
INVALID_PAYLOAD	The argument failed validation	An out-of-range zoom, or an unknown chrome flag
TIMEOUT	No answer arrived in time	A host origin the map rejected, or a frame that never loaded
PROTOCOL_MISMATCH	The map speaks a protocol this SDK does not	A major protocol change with an unusually old SDK
DESTROYED	The handle was destroyed, or the mount was aborted	Teardown racing an in-flight command
INVALID_OPTIONS	The arguments were rejected before anything was sent	A container selector matching nothing, or a malformed hostOrigin
INTERNAL	An unexpected failure inside the map	Worth reporting, with map.build if you have it

Codes are contract. They are deprecated rather than renamed.

Diagnosing a silent map

A map that renders correctly and ignores every command almost always means the host origin did not match. The map compares the sender of each message against the host parameter in its URL by exact string equality and drops anything that does not match, without replying, so the symptom on your side is TIMEOUT on every command rather than a specific error.

Replying would mean posting a message to an origin that has already been judged untrusted, which both confirms the map is there and hands the sender a channel. Silence is the correct behaviour, and it is why the SDK validates the origin on your side, where a real message can be attached.

Check that the URL's host parameter is your page's exact origin: scheme, host, and port, with no path and no trailing slash. mount() and the React component fill this in for you, so this is a concern only when you build the URL yourself.

Errors that are not rejections

map.error is an event rather than a rejection. It reports failures inside the map that no particular command caused, such as a campus that failed to load.

map.on("map.error", ({ code, message }) => {
  reportToMonitoring(code, message);
});

Next

• Protocol errors for the wire-level codes.
• Compatibility for what UNSUPPORTED and PROTOCOL_MISMATCH imply about versions.