Every error

Every error a @fkn/lib 0.9.28 call can produce has a row on this page, and a few rows list more than one wording of the same error. This page groups the rows by the calls that produce them and says, for each, what happened, what to do and whether a retry can succeed.

handling errors explains how to match a row. It also lists which fields of an error survive the hop out of the broker, the connection your app holds into FKN.

The handler below sorts an error into five branches by the shape it arrives in. The guards overlap, so test them in this order:

app.ts

import { cloud, isLocatorDenied, isTerminalError } from '@fkn/lib'
import { isNotFound, StorageLockedError } from '@fkn/lib/cloud/fs'
import { E2E_INTEGRITY_MESSAGE, E2E_STALE_EPOCH_MESSAGE } from '@fkn/lib/messages'
import { BrokerUnreachableError } from '@fkn/lib/api'

const handle = (error: unknown) => {
  // absence and locked, a code and a class, both minted in your own realm
  if (isNotFound(error)) return null
  if (error instanceof StorageLockedError) return promptUnlock()

  // everything else from the broker, by message prefix
  const message = error instanceof Error ? error.message : ''
  if (message.startsWith(E2E_STALE_EPOCH_MESSAGE)) throw error // never retry, never overwrite
  if (message.startsWith(E2E_INTEGRITY_MESSAGE)) throw error // never overwrite
  if (message.startsWith('storage: api unreachable')) return keepLocalCopy()
  if (message.startsWith('FKN: the broker was replaced')) return retryOnce()

  // locators and frames, by name, through the exported guards
  if (isLocatorDenied(error)) return explainRefusal()
  if (isTerminalError(error)) return giveUp()

  // the consent refusal, its own name, matched by neither guard above
  if (error instanceof Error && error.name === 'PermissionDeniedError') return explainRefusal()

  // the broker deadline, a real class, minted in this realm
  if (error instanceof BrokerUnreachableError) return waitAndRetry()

  throw error
}

const catalog = await cloud.fs.promises.readFile('library/catalog.json', 'utf8').catch(handle) // the catalog, or null when nothing is stored yet

On a first run nothing is stored yet, so the read resolves to null. The closing throw passes on a PackagesError or a node-style storage code. Both are matched on code, as their sections below show.

The same handler serves every call site. A storage read never reaches the locator, consent or broker-deadline branches. A realm is one JavaScript execution context, such as a window, a worker or a package tenant. handling errors lists which errors cross out of one.

Type any part of a message, a name, a call or an instruction to narrow every table at once:

Filter rows

Each row has an anchor made from the fixed prefix of its message, the part you match on. /errors/#storage-api-unreachable keeps working for as long as that prefix does. When two rows share a prefix, the later row carries an anchor of its own, as Permission denied: <key> (<scope>) does.

fetch()

The root fetch, cloud.fetch and extension.fetch produce these errors, and so do the two header-rule calls, extension.setRequestHeaderRule and extension.removeRequestHeaderRule:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
fetch refuses FKN platform domains (<hostname>)	Error	fetch, cloud.fetch	The target hostname is fkn.app, fkn.dev, sdbx.app or any dot-anchored subdomain of them. A trailing dot is stripped first, so fkn.app. and fkn.app%2e are the same name.	Point the call at the app's own api. A capability that carries the user's identity is never aimed at a platform origin.	No
fetch: refusing to target the extension's own pages or FKN platform domains	Error	extension.fetch, and the root fetch whenever the extension backend is chosen	The url scheme is chrome-extension: or moz-extension:, or the hostname is a platform host. The extension checks this a second time in its content script, so calling the bridge directly does not skip it.	Point the call at the app's own api, as for the row above.	No
fetch with credentials needs the FKN extension, which only exists in window realms	Error	root fetch with credentials: 'include'	The realm has no document, so there is no content script to reach and no session to spend.	Do the credentialed call on the main thread, or drop to credentials: 'omit' and let the cloud backend serve it.	No
The FKN WebExtension is not installed, enabled or not exposed on this page.	Error	extension.fetch, root fetch with credentials: 'include', extension.attachFrame, attachFrame, cookies.get, permissions.request, setRequestHeaderRule, removeRequestHeaderRule: everything that goes through the extension bridge	The extension marker data-fkn-extension did not appear within 1000 ms plus a 150 ms grace after load, and the install prompt did not produce a usable extension. In a worker realm this arrives as a ReferenceError instead, because MutationObserver and document do not exist there.	Offer promptInstall(reason) or a link to the store listing, then retry once the user has installed or enabled it.	Yes, once the user installs or enables it
fetch: refusing to forge request header(s): <names>	Error	extension.fetch	The init.headers carried a header outside the forgeable set origin, referer, cookie. <names> is the deduplicated lowercase list.	Send only the three forgeable names through that slot. Every other header is a normal request header and goes through untouched.	No
fetch: a forged Cookie header and credentials:'include' are different identities - send one or the other	Error	extension.fetch	Both a non-empty forged cookie header and credentials: 'include' were passed.	Pick one identity and drop the other. There is deliberately no precedence rule.	No
fetch: could not install the header rule for a forged Cookie, so the request was not sent unauthenticated	Error	extension.fetch with a forged cookie	The session rule that carries the cookie could not be installed, for example because the url is too long for the rule filter. The request is not sent rather than sent without the cookie.	Shorten the url or drop the forged cookie. A failed rule for origin or referer is not fatal: that request runs without the header.	Sometimes, with a shorter url
FKN cloud.fetch: no proxy is available (the relay directory could not be read, and no fallback origin is configured)	Error	cloud.fetch, root fetch on the cloud path	The ranked relay directory produced no proxy origin, and the published build carries no fallback origin.	Retry after a short backoff. The endpoint cache lives 30000 ms and a cooled relay is retried after 60000 ms.	Yes
request rule <id> was not issued to this document	Error	removeRequestHeaderRule(ruleId)	The rule id was never issued to this frame, or was issued for a different rule kind.	Remove only the ids your own setRequestHeaderRule returned.	No
Whatever new Request(input, init) throws, typically a TypeError	TypeError	extension.fetch	The extension path normalises through a real Request first, so a GET with a body, or a ReadableStream body without duplex: 'half' on Chromium, throws before anything is sent. The text is the browser's.	Fix the init so the browser accepts it.	No
Permission denied: network.fetchCredentialed (<scope>), Permission denied: network.fetchLocal (<scope>)	PermissionDeniedError, with permissionKey and scope	extension.fetch, root fetch with credentials: 'include'	The user refused, or a stored deny covers the scope.	Match error.name === 'PermissionDeniedError'; neither isLocatorDenied nor isTerminalError matches it. See Permissions and consent.	Yes, if the user changes their mind
400 {"error": "fkn-proxy-protocol must be http or https"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The target url scheme is neither http nor https.	Use an http or https url. Check response.ok and read error from the JSON body.	No
400 {"error": "missing fkn-proxy-hostname"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	No hostname reached the proxy.	Pass an absolute url that carries a hostname.	No
403 {"error": "proxying FKN platform domains is not allowed"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The proxy keeps its own copy of the platform host list (fkn.app, fkn.dev, dot-anchored). The library and the broker already refuse sdbx.app before the request leaves, so the server list is shorter by one suffix.	Point the request at the app's own api; a platform host is never proxied.	No
403 {"error": "egress refused (non-public target)"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	Every resolved address of the target is checked and one was in a private, loopback, link-local, multicast or documentation range. The check runs inside the DNS resolver too, so the dialed address is the validated one.	Target a public address. A host on the local network is reachable through the extension backend, which asks the user for network.fetchLocal.	No
429 {"error": "rate limit exceeded"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The per-caller request-rate budget for this tier is spent.	Wait, then retry; the budget refills.	Yes, after a wait
429 {"error": "upstream origin is saturated"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The proxy holds too many concurrent requests to that one upstream origin for this caller.	Retry, and cap how many requests the app keeps open against one origin.	Yes, immediately in most cases
413 {"error": "request body exceeds POST_MAX_BODY_SIZE"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The request body is larger than the configured cap.	Send a smaller body, or split the upload.	No
502 {"error": "upstream fetch failed: <e>"}	No error: the Response resolves with ok: false	cloud.fetch, and the root fetch on the cloud path	The upstream connection or read failed. <e> is the transport error text.	Retry. Read <e> for what the upstream did.	Yes

A row marked No error describes a call that resolves. Check response.ok and the error field of the body instead. The details are on fetch().

Sockets

Node’s net, dgram, http and dns fail with these errors, and so do their cloud aliases:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
FKN WebVPN does not support IPC connections	Error	net.Socket#connect, net.createConnection, net.Server#listen	The first argument is a string (a unix socket path) or a Node handle. Thrown synchronously by the argument normaliser.	Use a port, or a { port, host } object.	No
FKN WebVPN does not support file descriptors	Error	new net.Socket({ fd })	options.fd is set.	Drop fd.	No
Socket not connected	Error	net.Socket#_read, #_write (as the write callback's error), #end, #destroy internals	A read, write or teardown ran before connect() armed the socket promise.	Call connect() first, or wait for the connect event.	No, until connect() is called
Socket is not connected	Error	net.Socket#localAddress, #localPort, #localFamily, #remoteAddress, #remotePort, #remoteFamily	The endpoints have not landed yet. The getters throw rather than answer undefined.	Read them inside the connect handler. socket.address() answers {} instead of throwing.	Yes, after connect fires
Method not implemented.	Error	net.Server#getConnections(cb)	The browser transport has no connection table.	Count connection events yourself.	No
Cannot set socket option before connect	Error, emitted as 'error'	net.Socket#setKeepAlive, #setNoDelay and friends before connect	The socket promise does not exist yet. Emitted, not thrown.	Set options after connect.	No
Missing options	Error	new dgram.Socket()	The constructor requires options. The @fkn/dgram shim's type cast hides this, so new Socket() typechecks and throws at run time.	Use dgram.createSocket('udp4').	No
Socket not bound	Error	dgram.Socket#close, #connect, #disconnect, #send internals	The socket was never bound. Thrown synchronously.	Call bind() first, or use send(), which binds on its own.	No, until bind()
ERR_SOCKET_DGRAM_NOT_CONNECTED	Error (the code is the whole message)	dgram.Socket#disconnect, #remoteAddress()	The socket holds no remote.	Call connect(port, address) first.	No
EBADF	Error (the code is the whole message)	dgram.Socket#address()	No local address yet.	Read it inside the listening handler.	Yes, after listening
"offset" is outside of buffer bounds, "length" is outside of buffer bounds	RangeError, code ERR_BUFFER_OUT_OF_BOUNDS	dgram.Socket#send(msg, offset, length, ...)	The range form was used with an offset or length outside the payload. Thrown synchronously.	Fix the range.	No
Invalid multicast address: <address>	Error, emitted as 'error'	dgram.Socket#addMembership, #dropMembership	The string parses as neither IPv4 nor IPv6.	Pass a literal group address.	No
Invalid IPv4 address: <s>, Invalid IPv6 address: <s>	Error	dgram.Socket#send on the data-port path, #setMulticastInterface	An address literal failed to encode into wire bytes.	Pass a valid literal.	No
Cannot set headers after they are sent to the client	Error, code ERR_HTTP_HEADERS_SENT	http OutgoingMessage#setHeader	The head block already went out.	Set headers before the first write.	No
Cannot render headers after they are sent to the client	Error, code ERR_HTTP_HEADERS_SENT	http ServerResponse#writeHead	writeHead was called twice, or after the head went out. Node merges instead; this throws.	Call writeHead once.	No
Cannot remove headers after they are sent to the client	Error	http OutgoingMessage#removeHeader	The head block already went out.	Remove headers before the first write.	No
Header name must be a valid HTTP token [<name>]	TypeError, code ERR_INVALID_HTTP_TOKEN	http OutgoingMessage#setHeader	The name is not a string or fails the HTTP token pattern.	Fix the name.	No
Invalid value "undefined" for header "<name>"	TypeError, code ERR_HTTP_INVALID_HEADER_VALUE	http OutgoingMessage#setHeader	The value is undefined.	Pass a value or omit the header.	No
Socket is not available	Error, passed to the write callback	http OutgoingMessage#write, #end	The response is not bound to a socket.	Stop writing once the socket is gone.	No
@fkn/lib: no broker connection within <ms>ms, so <what> could not be requested	BrokerUnreachableError	net.Socket#connect (<what> is an outbound tcp socket), net.Server#listen (a tcp listener), dgram.Socket#bind (a udp socket)	No broker connection exists within the deadline: 8000 ms the first time, 1000 ms after any miss. In a worker realm this is the normal answer until the page calls relayWorker.	Bridge the worker with relayWorker(worker), or wait and retry. See Connection and lifecycle.	Yes, once the broker is up
getaddrinfo ENOTFOUND <hostname>	Error	net.Socket#connect, net.Server#listen, dgram.Socket#bind, #connect, #send to a hostname	The broker's own dns.lookup returned nothing for the name. The code, errno, syscall and hostname fields are set in the broker realm and are not guaranteed to survive the hop.	Match the message, not the code. Check the name; dns.lookup(hostname) answers the same question directly.	Sometimes, DNS can change
tcp connect to <address>:<port> timed out after 12000ms	Error	net.Socket#connect	The relay did not acknowledge the connect within 12000 ms.	Retry. If the session produced no metadata at all the transport is also marked stalled and the next dial picks another relay.	Yes
The upstream OS error text, for example Connection refused (os error 111)	Error	net.Socket#connect	The relay dialed the target and the kernel refused or reset. The relay's own I/O error string is truncated for the wire and rethrown verbatim in the app realm, so the text is the operating system's; the example is the Linux wording and is illustrative.	Handle it as you would Node's ECONNREFUSED, matching the text: no Node code survives the hop.	Depends on the peer
webvpn: egress to a non-public address refused	Error	net.Socket#connect, net.Server#listen, dgram.Socket#bind, #connect	The target resolves to a loopback, private, link-local or otherwise non-public address and private-target filtering is on. A loopback target is paired locally first, so this is only reached when no local listener owns the port.	Use a public target, or a local net.Server in the same broker data plane for loopback pairing.	No
webvpn: socket capacity reached	Error	net.Socket#connect, net.Server#listen, dgram.Socket#bind	The session's per-session socket budget is spent.	Close what you no longer need, then retry.	Yes, after closing sockets
webvpn: socket control queue saturated	Error	net.Socket#connect, net.Server#listen, dgram.Socket#bind	The session's metadata control queue is full.	Back off and retry.	Yes
webvpn: account session capacity reached	Error	any socket call that opens a new relay session	The account already holds the maximum number of relay sessions.	Close another tab or device that is using the relay, then retry.	Yes, after closing a session elsewhere
webvpn: token not accepted	Error	any socket call that opens a new relay session	The rate token presented at session setup was refused.	Reconnect the account; a fresh token is minted in the background.	Yes
webvpn: broadcast is not available while private-target filtering is enabled	Error	dgram.Socket#setBroadcast then #send to a broadcast address	Broadcast is off while the private-target filter is on.	Use a unicast target.	No
WebVPN setup timeout: <what> took over <ms>ms	Error	net.Socket#connect, net.Server#listen, dgram.Socket#bind	A setup step (for example tcp data stream claim) did not complete inside its deadline.	Retry.	Yes
WebVPN session closed	Error	every socket, on its 'error' event, and dgram.Socket on transport close	The relay session ended under the socket. The dgram path substitutes the close reason when the transport supplied one.	Reopen the socket. dgram only emits this when an 'error' listener is attached, so 'close' is never swallowed.	Yes, a new call redials
FKN WebVPN: no relay reachable	Error	the first socket call in a realm	Every ranked relay failed to dial and none produced a more specific error.	Retry after a backoff. A failed relay cools for 60000 ms.	Yes
relay directory returned <status>, relay directory answered <content type>, relay directory is empty, no relay directory is configured	Error	the first socket call in a realm	The relay directory fetch failed, answered the wrong content type, listed nothing, or is unset.	Retry the first three; the fourth is a build without a directory and needs a rebuild.	Yes for the first three
tcp listener closed	Error	net.Server, on pending accept claims	The listener was closed while a connection claim was outstanding.	Ignore it during teardown.	No, the server is closed
tcp listener already unbound by relay, tcp socket already shut down by relay	Error	net.Server#close, net.Socket#end, #destroy	The relay tore the resource down before the local teardown ran.	Ignore it during teardown.	No
Invalid packet type <type>, expected <expected>	Error	any socket call	The relay answered with a packet the client did not expect, which means the two ends disagree on the wire format.	Report it. A reload picks up a newer broker.	No

A refused connect, bind or listen reports its error on the socket’s error event. The details are on TCP and UDP sockets and HTTP and DNS.

Storage

cloud.fs, the hybrid fs and opfs share these errors, including the messages the storage service itself returns:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
storage locked: this account stores encrypted data, unlock it from the FKN card or unlock()	StorageLockedError, code FKN_E2E_LOCKED	cloud.fs.readFile, readFileSealed, writeFile, and the same members through promises	The broker holds no usable key for this app. The call raises the unlock card first and waits; this error arrives only after the card is dismissed, when no window can show it, or when the popup delivered no usable key.	Call unlock() or point the user at the FKN card, then retry. The message deliberately does not match /not found/: locked is unreadable, not empty. See Encryption.	Yes, after unlock()
storage: no object at that path, or the original sentence (Not found, storage: read failed (404))	StorageNotFoundError, code FKN_STORAGE_NOT_FOUND	cloud.fs.readFile, readFileSealed, writeFile	There is no object at the path. Absence arrives worded two different ways: the api refusing to presign a path with no committed row, and a presign that succeeded followed by a 404 on the object. Both re-mint to this one class.	Test isNotFound(err) or err.code === STORAGE_NOT_FOUND, never the message. "Nothing here" is safe to overwrite; "I could not tell you" is not.	No
storage: api unreachable	Error (a FKN_API_UNREACHABLE code is set in the data plane and does not reliably survive the hop)	every cloud.fs member	The fetch to the api's GraphQL endpoint threw. Distinct from an answered error on purpose: a caller may relax an obligation on "nobody answered", never on an answered 500.	Match message.startsWith('storage: api unreachable'). Keep the local copy and retry later.	Yes
storage: not connected	Error	every cloud.fs member	No connect token for this scope, so the account is not connected to this site.	Call connect() or account.login(). See Account and quota.	Yes, after connect()
storage: reserved path	Error	cloud.fs reads, writes and deletes on .fkn or .fkn/*	That prefix is platform-internal.	Use another path.	No
storage: read failed (<status>)	Error	cloud.fs.readFile, readFileSealed	The presigned object fetch answered a non-2xx other than 404. A 404 becomes StorageNotFoundError instead.	Retry.	Yes
storage: write failed (<status>)	Error	cloud.fs.writeFile	The presigned upload PUT answered a non-2xx.	Retry.	Yes
storage query failed: <status>	Error	every cloud.fs member	The GraphQL response was not ok, or carried no data, and no errors array explained it.	Retry.	Yes
Invalid path	Error	cloud.fs reads, writes, deletes, rename	The path is empty, longer than 1024 characters, has more than 64 segments, holds a control character, or has any empty, . or .. segment. A leading slash produces an empty first segment, so /library/catalog.json is refused.	Use a relative path such as library/catalog.json.	No
Storage quota exceeded	Error	cloud.fs.writeFile	The account's byte limit would be passed. Checked at presign and again at commit.	Delete something or upgrade. cloud.fs.quota() reports the headroom.	No, until space is freed
Object limit exceeded	Error	cloud.fs.writeFile	The account holds the maximum number of objects and this write would add one more.	Delete an object first.	No
Object too large	Error	cloud.fs.writeFile	The declared size, or the uploaded object's real size, is over the per-object cap.	Split the file.	No
Concurrent update, retry	Error	cloud.fs.writeFile, unlink	Another writer moved the row between the presign and the commit, or between reading and deleting. The compare-and-set refused.	Retry the whole write.	Yes
Upload not found	Error	cloud.fs.writeFile	The commit named an upload key with no object behind it.	Retry the write from the start.	Yes
Not signed in	Error	every cloud.fs member	The bearer resolved to no live session, or its credential generation is stale. The data plane also reports a connect refusal when it sees this exact sentence.	Call account.login().	Yes, after signing in
Storage is not configured	Error	every cloud.fs member	The api instance has storage disabled.	Report it; the app cannot change this.	No
Not found	Error	cloud.fs.unlink and other members on a .fkn-prefixed or absent row	The row does not exist, or the path starts with the platform prefix. On readFile and writeFile this is re-minted to StorageNotFoundError; unlink does not run the re-mint, so it arrives as a plain Error and isNotFound answers false.	For deletes, match the message, or treat any delete failure as best effort.	No
<CODE>: <text>, <syscall> '<path>'	Error, with code, path and syscall	every node-style member of fs, opfs, cloud.fs	The usual filesystem conditions, for example ENOENT: no such file or directory, stat 'a/b'. Codes in use: ENOENT, EEXIST, ENOTDIR, EISDIR, ENOTEMPTY, ERR_FS_EISDIR, EBUSY, EINVAL.	Branch on err.code exactly as with Node's fs.	Depends on the code
storage: <path> exists but could not be read, retry once its scope is available	Error, code FKN_E2E_LOCKED	fs.readFileSync, statSync, writeFileSync, renameSync, open, stat, rename on an unhydrated path	The path is known from a listing but its bytes could not be read into the memory copy, typically because the account is locked. Such a path still answers exists() and still appears in readdir.	Unlock, then remount(). Deleting it needs no key.	Yes, after unlock()
The "data" argument must be of type string, Buffer, TypedArray, or DataView	TypeError	fs.writeFile, writeFileSync, appendFile, appendFileSync, and the cloud.fs equivalents	A Blob, an object or anything else was passed as the data.	Convert to bytes first. Only a conflict resolver may hand back a Blob.	No
opfs: invalid path	Error	fs.pull(path), fs.readFileSealed(path), and every direct opfs member	The path holds a .. segment, or normalises to nothing. The memory layer never sends .., but pull and readFileSealed pass the raw string.	Normalise the path before calling.	No
fs: cloud unreachable	Error	fs.writeFile, remove, adopt	The cloud state probe answered 'unknown', so nobody could be asked, and there is no local half to queue from. Kept distinct from the row below on purpose.	Retry. The probe costs up to 8000 ms the first time and 1000 ms after a timeout.	Yes
fs: no storage backend available	Error	fs.writeFile, remove	No OPFS in this realm and the account answered a definite sign-out.	Sign in, or accept that this realm has no durable store.	Yes, after signing in
fs: this needs a signed-in account	Error	fs.adopt()	The cloud half answered 'disconnected'.	Call account.login() first.	Yes, after signing in

Only a read or a write turns the locked and not-found rows into a StorageLockedError or a StorageNotFoundError. A cloud.fs.unlink failure is not converted, so isNotFound returns false for it. The node-style members carry Node’s own error.code, listed on storage.

Encryption

Encryption has three messages of its own, exported as constants from @fkn/lib/messages. The storage service answers with four more on a write:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
fkn:e2e-locked	Error on the wire, re-minted to StorageLockedError in the app realm	cloud.fs reads and writes	The broker holds no usable key for this app. This is the wire form of storage locked, exported as E2E_LOCKED_MESSAGE.	Handle StorageLockedError instead; match this prefix only when reading the raw broker error, as a package does.	Yes
fkn:e2e-stale-epoch: this file is encrypted under a previous key you reset	Error	cloud.fs.readFile, readFileSealed	The object was sealed under a key generation the user has since reset. The old key is gone everywhere. Exported as E2E_STALE_EPOCH_MESSAGE.	Do not retry and do not overwrite blindly. The only way back is an encrypted export taken before the reset. See Encryption.	No, never
fkn:e2e-integrity: stored data failed its integrity check	Error	cloud.fs.readFile, readFileSealed	The row carries no seal marker, an unknown marker, a scope that disagrees with the bearer, or an envelope whose tag did not verify. Exported as E2E_INTEGRITY_MESSAGE.	Never overwrite the path on this error. Surface it and stop.	No
Superseded key	Error	cloud.fs.writeFile	The account's key rotated between sealing the bytes and committing them. The commit names the generation it sealed under, so this is caught rather than silently stored.	Retry the write; it reseals under the current generation.	Yes
This account has no encryption keys yet	Error	cloud.fs.writeFile	The account holds no key record, which is what a settled key reset leaves behind.	Send the user to the security page to enrol again. cloud.fs.encryption() answers enrolled: false in this state.	Yes, after re-enrolling
This account stores sealed objects	Error	cloud.fs.writeFile	A write arrived with no seal marker for an account that stores sealed objects.	Report it; the broker seals every write, so an app cannot produce this on its own.	No
Invalid encryption	Error	cloud.fs.writeFile	The marker on the commit is not one the api recognises.	Report it; the marker is set by the broker, not by the app.	No

Never retry or overwrite after the stale-epoch row (the file was encrypted under a previous key generation) or the integrity row. The reasons are on encryption.

Frames

attachFrame, extension.attachFrame and cloud.attachFrame produce these errors. So do goto and the liveness checks that every later call on the Frame runs:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
cloud.attachFrame needs a window realm	Error	cloud.attachFrame, and attachFrame when it falls to the cloud backend	No window.	Attach on the main thread.	No
cloud.attachFrame does not support lockdown; use the extension backend for a sealed frame	Error	cloud.attachFrame	lockdown: true was passed. attachFrame routes lockdown to the extension backend before this can fire; only a direct cloud.attachFrame call reaches it.	Use extension.attachFrame, or drop lockdown.	No
cloud.attachFrame: the iframe must be connected to the document before attaching	Error	cloud.attachFrame	The iframe is not in the document.	Append the iframe first.	Yes, after appending it
cloud.attachFrame: the iframe's sandbox attribute must include <tokens> for the render proxy to load	Error	cloud.attachFrame	A sandbox attribute is present without allow-scripts and allow-same-origin. No sandbox attribute at all is fine.	Add the tokens or remove the attribute.	No
cloud.attachFrame: the iframe src is not a valid URL: <src>	Error	cloud.attachFrame	The src attribute is present but does not resolve to a URL.	Fix the src, or leave it empty and use goto.	No
cloud.attachFrame: this iframe is already attached; navigate with the Frame returned by that attach or use a fresh iframe	Error	cloud.attachFrame	The src already points at the render proxy page.	Reuse the Frame from the first attach, or use a fresh iframe.	No
attachFrame: refusing to target the extension's own pages or an FKN platform origin	Error	cloud.attachFrame, extension.attachFrame, attachFrame	The target is an extension page or a platform host. Checked page-side for a fast error and again authoritatively in the content script and the render proxy page.	Point the frame elsewhere.	No
cloud.attachFrame: the iframe window is not available	Error	cloud.attachFrame	contentWindow is null right after src was set.	Retry with a fresh iframe.	Yes
cloud.attachFrame: timed out connecting to the render proxy page	Error	cloud.attachFrame	The handshake with the render proxy page did not connect within 20000 ms. On failure the iframe's referrerPolicy, allow and src are restored.	Retry.	Yes
cloud.attachFrame: the render proxy never became ready	Error	cloud.attachFrame	The render proxy page connected but did not report ready within 65000 ms.	Retry.	Yes
attachFrame: lockdown needs domains when the frame already has a src; pass domains or load it via goto	Error	extension.attachFrame, attachFrame with lockdown	A headers-based lockdown cannot cover a document that is already loading.	Pass domains, or attach a blank iframe and goto.	No
attachFrame: the iframe must be connected to the document before attaching	Error	extension.attachFrame, attachFrame	The iframe is not in the document. Checked after the exposure wait, so a missing extension is reported first.	Append the iframe first.	Yes
frame: no iframe registered for marker="<marker>"	Error	extension.attachFrame	The CustomEvent carrying the attach marker never reached the content script.	Retry the attach.	Yes
The FKN WebExtension is not installed, enabled or not exposed on this page.	Error	extension.attachFrame, attachFrame	The exposure wait runs before the connected-iframe check, so a missing extension is reported first. ExtensionOutdatedError would be the other outcome of the same wait, but cannot fire in this version.	Offer promptInstall(reason) or a link to the store listing, as for the fetch row of the same name.	Yes, once installed
frame goto: "<url>" is not a url this page can resolve	Error	extension frame.goto	The url does not resolve against the app page's location.href.	Pass an absolute url.	No
frame load failed for <href>	Error	extension frame.goto with the default waitUntil: 'load'	The iframe fired error.	Retry, or check the target.	Yes
frame load timed out after <ms>ms for <href>	Error	extension frame.goto	No load within timeoutMs, default 30000.	Raise timeoutMs or retry.	Yes
frame goto: documentstart timed out	Error	extension frame.goto with waitUntil: 'documentstart'	The new document's content script did not announce itself in time.	Retry.	Yes
cloud.attachFrame: the render proxy did not answer goto; the frame may have been detached or its page reloaded	Error	cloud frame.goto	The render proxy page did not answer within timeoutMs (default 30000) plus 5000 ms.	Check the frame is still attached, then retry with a fresh attach.	Sometimes
navigation to <url> did not commit; the frame is still blank	Error	cloud frame.goto	The render proxy navigated but no document committed.	Retry.	Yes
frame load timed out after <ms>ms for <url>	Error	cloud frame.goto	The render proxy's own load deadline passed.	Retry.	Yes
Permission denied: embed.open (<href>)	PermissionDeniedError	extension frame.goto	The user refused the navigation.	Match error.name === 'PermissionDeniedError' and explain the refusal. See Permissions and consent.	Yes
cloud.attachFrame: the attached iframe left the document or was reloaded; attach a fresh iframe	LocatorUnsupportedError	every locator call and goto on a cloud Frame	The iframe was detached, an ancestor was removed, or contentWindow changed. Only the direct parent is watched; an ancestor removal is caught on the next call. The name is set deliberately so the dispatch loop stops instead of retrying a dead channel.	Attach a fresh iframe.	No, this attachment is over
frame: this frame no longer holds the document the app attached it to	LocatorDeniedError (terminal)	every locator call on an extension Frame	The framed document navigated somewhere the app never declared. The message deliberately does not say where it went.	goto a declared target again. The policy travels down every frameLocator hop.	No
frame: <operation> is only available on an attached frame	LocatorDeniedError (terminal)	frame.fetch on a frame that is not an attachment	fetch is refused outright on a frame that is not an attachment.	Use the Frame returned by attachFrame.	No

What each backend (the cloud, the extension or the desktop) refuses is on frames, and how long goto waits is on timeouts.

Locators

Every selector and action on a Locator can fail with these errors, and so can the frameLocator and owner calls and frame.fetch:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
No elements found	LocatorError	click, fill, hover, textContent, getAttribute, isVisible, videoElement	The chain resolved to nothing. This is the message a "timeout" usually carries, since the loop rethrows the last attempt.	Widen the selector, or raise timeout.	Yes, to the deadline
Strict mode violation: locator resolved to <n> elements	LocatorError	the same operations	The chain matched more than one element and the operation needs exactly one.	Narrow the selector. count and exists accept any number.	Yes, to the deadline
Strict mode violation: expected <name>, got <tag>	LocatorError	videoElement and other tag-pinned operations	The single match is the wrong element type.	Fix the selector.	Yes
Locator timeout (<ms>ms): <operation>	Error	any operation	The deadline passed with no attempt having failed first, for example a single attempt that hung.	Raise timeout, or find out why the attempt hangs.	No
fill: element <tag> is not fillable	Error	fill	The element is not an <input>, <textarea> or contenteditable node.	Target a real field.	Yes, pointlessly
frameLocator: no <iframe> matched	LocatorError	any call whose chain crosses a frameLocator	The barrier selector matched nothing.	Wait for the iframe, or fix the selector.	Yes, to the deadline
frameLocator: expected <iframe>, got <<tag>>	LocatorError	any call whose chain crosses a frameLocator	The barrier's first match is not an iframe.	Fix the selector.	Yes
frameLocator: this realm has no bridge into child frames	LocatorUnsupportedError, operation 'frameLocator'	any call whose chain crosses a frameLocator	The realm cannot descend.	Do not descend from this realm; drive the child from a realm that has a bridge.	No
frameLocator: <iframe> has no contentWindow	Error	any call whose chain crosses a frameLocator	The iframe holds no window yet.	Wait for it to load.	Yes
owner: this realm has no bridge to its parent frame	LocatorUnsupportedError, operation 'owner'	owner()	No upward bridge in this realm.	Do not climb from here.	No
owner: already at the top frame	LocatorUnsupportedError, operation 'owner'	owner()	The chain is already at the top.	Stop climbing.	No
owner: the parent frame is outside this bridge boundary	LocatorUnsupportedError, operation 'owner'	owner() on the render proxy	The bridge refuses to climb out of the proxied content.	Stop climbing.	No
the frame this call was routed to went away mid-call, retrying	LocatorError	any call across a frameLocator hop	The child frame navigated mid-call.	Let the dispatch loop retry; no handling is needed.	Yes, to the deadline
the attached frame became stale during the call, retrying	LocatorError	any call on an extension Frame	The attached frame navigated mid-call.	Let the dispatch loop retry; no handling is needed.	Yes
frame-locator: the target frame has no window yet, frame-locator: registration <id> went away before it answered, retrying	LocatorError	any call across a window bridge	Bridge registration raced the call.	Let the dispatch loop retry; no handling is needed.	Yes
Unknown locator kind: "<kind>", Unknown selector: "<kind>.<name>"	LocatorUnsupportedError	a chain built with a selector this stack does not register	The selector module is not in the registry. @fkn/lib's Locator is pre-bound to the extension stack's registry, which adds videoElement and the reason option.	Use the registered selectors. See Locators and actions.	No
Locator operation not supported on the <backend> backend: <operation>	LocatorUnsupportedError, with operation and backend	any operation a backend refuses	The backend does not serve that operation.	Use the other backend.	No
<operation>: selectors matching the value attribute need a consent-gated operation	Error	severity-0 operations (isVisible, count, exists) whose chain probes [value=...]	A silently auto-granted operation may not read a field's value through a selector.	Use a gated operation such as getAttribute.	No
requestPictureInPicture is not supported in this environment, exitPictureInPicture is not supported in this environment	Error	videoElement().requestPictureInPicture(), .exitPictureInPicture()	The framed document's browser lacks the method.	Feature-detect first.	No
videoElement: unknown method "<method>"	Error	a videoElement handle method that does not exist	Only play, pause, load, requestPictureInPicture and exitPictureInPicture are callable.	Call one of the five methods that exist.	No
Index or size is negative or greater than the allowed amount	DOMException, name IndexSizeError	videoElement state's buffered.start(i), .end(i), seekable.*	The index is out of range on the rebuilt TimeRanges.	Check length first.	No
fetch: url must be a string	LocatorInvalidError, operation 'fetch'	frame.fetch on either backend	The url argument is not a string.	Pass a string.	No
fetch: not a valid url: <url>	LocatorInvalidError, operation 'fetch'	frame.fetch	The url does not resolve against the landing document's baseURI.	Pass a valid url.	No
frame.fetch on the cloud backend needs its own session: attach with syncCookies: false	LocatorDeniedError (terminal)	cloud frame.fetch	The attachment uses the shared render proxy jar, which is one record shared by every app. No grant can lift this.	Re-attach with syncCookies: false.	No
frame.fetch: url must be a string	LocatorDeniedError (terminal)	cloud frame.fetch, and cloud ensure('fetch')	The page-side gate sees a non-string where the url should be. ensure('fetch') hits this because the gate reads the options object as the url.	Pass a url, or skip ensure('fetch') on the cloud backend.	No
frame.fetch on the cloud backend needs an absolute url	LocatorDeniedError (terminal)	cloud frame.fetch	A relative url resolves in the landing realm, which the app page cannot know.	Pass an absolute url.	No
frame.fetch: only http(s) urls are supported	LocatorDeniedError (terminal)	cloud frame.fetch	The scheme is neither http nor https.	Use http or https.	No
frame.fetch: the target is outside the origins this attachment declared	LocatorDeniedError (terminal)	cloud frame.fetch	The hostname is not in domains and the origin is neither the attach target nor a goto target. The message deliberately does not echo where the call tried to go.	Declare the host in domains at attach, or goto it first.	No
frame.fetch: the user did not grant this	LocatorDeniedError (terminal)	cloud frame.fetch	The consent card was refused or dismissed. A dismissal starts a 10000 ms cooldown during which the card is not shown again and the call fails closed.	Ask again after the cooldown, or explain why the app needs it.	Yes, after the cooldown and a grant
frame.fetch: the user has not granted this	LocatorDeniedError (terminal)	cloud frame.fetch	The render proxy page re-ran the same policy and found no stored grant, without prompting.	Ask again later, or explain why the app needs it.	Yes
frame.fetch: the call completed but its audit receipt could not be recorded; result withheld	LocatorDeniedError (terminal)	extension frame.fetch	The fetch ran but its activity-log receipt could not be written. The result is withheld rather than returned unrecorded, and the name is terminal so the loop does not re-issue a state-changing request.	Treat the request as having happened with an unknown result.	No
fetch on the shared render proxy session, fetch on a frame holding no proxied document; navigate first, fetch is not available while the proxied document is on its own origin	LocatorUnsupportedError, backend 'render proxy'	cloud frame.fetch	The render proxy's own refusals. The third fires whenever the proxied document sits on its own frame-host origin, which is the deployed default, so cloud frame.fetch normally ends here.	Use the extension backend for frame fetches.	No
navigation pending; the target document has not committed yet	Error (retryable)	any cloud locator call right after a waitUntil: 'documentstart' goto	The render proxy resolved the goto early and the document has not committed.	Let the dispatch loop retry; no handling is needed.	Yes, to the deadline

A timeout rarely says so. The retry loop runs until its 30,000 ms deadline and then throws the error from the last attempt. isTerminalError matches the three error names that stop the loop early, listed on locators and actions.

Permissions

Every gated extension call can fail with the consent refusal. It is the error your call gets when a user denies a row on the consent sheet, the prompt the extension shows before an action above severity 0. The permission channel has two errors of its own:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
Permission denied: <key>, Permission denied: <key> (<scope>)	PermissionDeniedError, with permissionKey and scope	every gated extension call: fetch with credentials: 'include', cookies.get, setRequestHeaderRule, every locator operation, frame.goto, frame.fetch, extension.attachFrame	The user refused, dismissed the consent sheet, or a stored deny covers the scope. A dismissal records deny with remember: 'once', so a retry asks again. The gate raises it before the retry loop, so it is not retried.	Match error.name === 'PermissionDeniedError'. isLocatorDenied and isTerminalError do not match this name, which is the single most common wrong assumption in this area. See Permissions and consent.	Yes if the user changes their mind; no while a session or always deny stands
permission rpc: the background answered with an unknown shape	Error	permissions.request and anything that consults the store	The background's reply did not match the expected envelope.	Retry; reload the extension if it persists.	Yes
Whatever response.error says	Error	permissions.request and anything that consults the store	The background answered a structured failure. Its store mints no sentence of its own, so the text is the message of whatever rejected under it, which is the extension's database layer in the browser; nothing in the library fixes it.	Read the text.	Depends

Neither locator guard matches Permission denied: <key> (<scope>). Compare error.name instead, as the handler above does. The full flow is on permissions and consent.

Packages

Every packages.* member, in the host app and in the package it loads, fails with a plain Error that carries one of six codes. @fkn/lib/packages types that shape as PackagesError:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
packages: no FKN transport in this realm - use relayWorker to bridge workers	Error, code unavailable	every packages.* member except attach, onConnect, isVisible, onVisibilityChange	Neither window nor self is available.	Call relayWorker(worker) from the page. See Workers.	Yes, after bridging
packages.<call>: caller identity is not established	Error, code unavailable	pick, install, uninstall, connect, mount, show, hide	The broker could not attribute the call to an app identity.	Retry after the broker connection settles.	Yes
packages.<call>: <uri parse failure>	Error, code invalid	install, uninstall, connect, mount, show, hide	The uri failed to parse. Underlying sentences: A source uri must be a string of 1 to 512 characters, '<input>' has no '<handler>:' prefix, No handler for '<handler>:', and packages: '<handler>:' is not served by the npm registry.	Pass npm:<name>.	No
packages.install: version must be a valid npm version string	Error, code invalid	install	The pinned version fails the version pattern.	Fix the version.	No
packages.install: could not persist the install record (storage may be full or blocked)	Error, code unavailable	install	The broker could not write the install record.	Free space, or check that storage is not blocked for the origin.	Yes
packages.search: query must be an object, packages.search: type must be a short lowercase token, packages.search: id must be a short lowercase token, packages.search: unknown origin '<origin>'	Error, code invalid	search, pick	The query is malformed.	Fix the query.	No
packages.search: the npm registry did not answer	Error, code unavailable	search, pick	The registry request failed.	Retry.	Yes
packages: could not resolve '<name>' from the npm registry	Error, code unavailable	install, pick	The packument fetch failed or answered a non-object.	Retry.	Yes
packages: '<name>' has no latest version, packages: '<name>' has no version '<version>'	Error, code invalid	install, pick	The registry knows the package but not that version.	Pick a published version.	No
packages: another package prompt is already open	Error, code unavailable	pick, install	The broker's exclusive UI slot is taken.	Wait for the open prompt to close, then retry.	Yes
packages.<call>: '<uri>' is not installed by this app	Error, code not-installed	connect, mount	This app holds no install record for the package.	Call packages.install(uri) first.	Yes, after install
packages.show: '<id>' is not connected by this app - connect() before showing it	Error, code not-installed	show	The package is installed but not connected.	Call connect(uri) first.	Yes
packages.<call>: '<uri>' has been disabled by the platform	Error, code denied	connect, mount	The platform has switched the package off.	Remove the package from the app; nothing app-side can lift this.	No
packages.show: a package cannot place its own frame	Error, code denied	show called from inside a package tenant	Only a host app may place a frame.	Place the frame from the host app, never from inside the package.	No
packages.<call>: '<pinned uri>' does not fit a sandbox origin - use a shorter package name	Error, code unaddressable	connect, mount	The version-pinned identity does not encode into a sandbox origin label.	Publish the package under a shorter name.	No
packages.connect: '<uri>' was released while connecting	Error, code not-installed	connect	The package was uninstalled mid-connect.	Reinstall and retry.	Yes
packages.connect: '<uri>' failed to boot: <failure>	Error, code unavailable	connect	The tenant frame reported a boot failure.	Read <failure>; it is the package's own boot error.	Sometimes
packages.connect: '<uri>' did not register a connection handler	Error, code timeout	connect	The tenant never called onConnect.	Add a packages.onConnect handler in the package. See Packages.	Sometimes
packages.connect: the package did not complete the connection	Error, code timeout	connect, mount, attach	The connection handshake on the port did not settle within 30000 ms.	Retry.	Yes
packages.connect: the package refused the connection, or the package's own nack text	Error, code unavailable	connect, mount, attach	The package's createPayload threw, or it sent a nack. The package's Error.message is used when it supplied one.	Read the text; it is the package's.	Depends
packages.connect: aborted before connecting	Error, code unavailable	connect, mount, attach with a signal	The signal aborted before or during the handshake.	Treat it as the normal result of aborting.	Yes
packages.connect: the package closed before connecting	Error, code unavailable	connect, mount	The broker's closed promise settled during the handshake.	Retry.	Yes
packages.show: pass an element or a rect	Error, code invalid	show	Neither placement option was given.	Pass one.	No
packages.show: a rect with finite x, y, width and height is required	Error, code invalid	show	The rect has a non-finite member.	Fix the rect.	No
packages.mount: pass the iframe to load the package into	Error, code invalid	mount	options.iframe is not an HTMLIFrameElement.	Pass one.	No
packages.mount: the iframe must be in the document before mounting into it	Error, code invalid	mount	A detached frame never navigates, so src would resolve into a 30 s wait for a tenant that is not booting.	Append the iframe first.	Yes, after appending
packages.mount: the iframe's sandbox attribute must include <tokens>, or the package cannot start	Error, code invalid	mount	A sandbox attribute without allow-scripts and allow-same-origin. The tenant boots a service worker on its own origin and needs both.	Add the tokens or remove the attribute.	No
packages.mount: this page is cross-origin isolated, so the iframe's allow attribute must include 'cross-origin-isolated' to hand that down to the package	Error, code invalid	mount from a cross-origin isolated page	Isolation defaults to self, so a page that does not hand it down silently drops the package to no SharedArrayBuffer.	Add cross-origin-isolated to allow before mounting.	No
packages.mount: the package did not register a connection handler	Error, code timeout	mount	The tenant did not report ready within 30000 ms. The frame is unmounted before this throws.	Add a packages.onConnect handler in the package. See Packages.	Sometimes
packages.mount: the package failed to boot, or the tenant's own failure text	Error, code unavailable	mount	The tenant reported a boot failure.	Read the text; it is the package's.	Depends
packages.mount: the frame was detached before it could connect	Error, code unavailable	mount	contentWindow went away between the ready message and the port handoff.	Retry with a stable iframe.	Yes

Branch on code. A worker that was never relayed has to be relayed from the page first. The codes are on packages and the worker case is on workers.

Rooms

Every member of @fkn/lib/rooms, and every method on a Room, fails with a plain Error that carries one of ten codes, typed as RoomsError:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
rooms: no such room	Error, code not-found	rooms.join	No room holds that uuid, and no snapshot of one is fresh enough to restore.	Ask for a current invite. A room ends when its last member leaves.	No
rooms: wrong room key	Error, code bad-key	rooms.join	The key half of the invite is not the key the room was created with.	Pass room.invite whole, <uuid>.<key>, rather than the uuid alone.	No
rooms: the invite carries no key	Error, code invalid	rooms.join	The invite has no dot, or nothing on one side of it, so @fkn/lib refuses it before the broker is asked.	Pass room.invite, or an id and a key joined by a dot.	No
rooms: no such member	Error, code not-found	room.grant, room.revoke, room.remove, room.block, room.unblock	The id names nobody this room holds.	Take ids from room.members() and from the room events, and drop one on a left event.	No
rooms: the room is full	Error, code full	rooms.join	The room already holds its member cap.	Wait for a member to leave, or create the room with a larger members.	Yes
rooms: too many rooms	Error, code full	rooms.create	This account, or this address without one, holds its cap of open rooms.	Leave a room before opening another.	Yes, once a room ends
rooms: too many connections	Error, code full	rooms.create, rooms.join	The connection cap for this member or this address is reached.	Leave a room this browser still holds, then join again.	Yes
rooms: too many blocks	Error, code full	room.block	The room's block set is full, and it refuses rather than dropping an entry.	Unblock somebody first, since dropping an entry would let them back in.	Yes, after an unblock
rooms: you are blocked from this room	Error, code blocked	rooms.join	A member holding block blocked this caller, and a block lives as long as the room.	Nothing app-side lifts it. A member holding block can call room.unblock(id).	No
rooms: you cannot send here	Error, code denied	room.send	This member's send is false, from the room default or from a revoke.	Read room.self.permissions.send and hide the composer while it is false.	Yes, after a grant
rooms: permission denied	Error, code denied	room.remove, room.block, room.unblock	The caller holds neither remove nor block, whichever the call needed.	Offer the control only while room.self.permissions carries the one it uses.	Yes, after a grant
rooms: not the room owner	Error, code denied	room.setDefault, room.grant, room.revoke	Only the owner sets defaults and moves permissions.	Compare room.self.id with room.owner before offering these three.	No
rooms: the owner cannot be removed	Error, code denied	room.remove, room.block	The target is room.owner, who stays for the life of the room.	Render no remove or block control against the owner.	No
rooms: the owner keeps every permission	Error, code denied	room.grant, room.revoke	The target is room.owner, whose four permissions are constant.	Skip the owner when you render per-member permission controls.	No
rooms: you cannot remove yourself	Error, code denied	room.remove, room.block	The target id is room.self.id.	Call room.leave(), which is the call that means leaving.	No
rooms: sending too fast	Error, code rate-limited	room.send	The per-member or per-room rate is spent, or the platform shed the message before it took a seq.	Queue the text and send it again a moment later, and never in a tight loop.	Yes
rooms: the message is too large	Error, code too-large	room.send	The text is over 4,096 bytes of UTF-8, or the sealed frame is over the wire cap. Nothing is trimmed.	Split the text and measure its UTF-8 byte length, not its character count.	Yes, with shorter text
rooms: rooms are unavailable	Error, code unavailable	rooms.create, rooms.join, and every member of a joined Room	There is no broker to ask, the broker was replaced while the call was pending, or the platform could not answer the handshake.	Check rooms.available() first, and open the room again from the invite.	Yes
rooms: rooms are not available	Error, code unavailable	rooms.create, rooms.join	Rooms are switched off on the platform, so every call is refused for now.	Branch on rooms.available() and offer the rest of your app without a room.	Sometimes
rooms: already joined	Error, code invalid	rooms.create, rooms.join	A second create or join reached one connection, which carries one membership.	Hold the Room the first call resolved and pass it around.	No
rooms: malformed frame	Error, code invalid	rooms.create, rooms.join, and every member of a joined Room	The platform could not read the frame, or a key or seed was not 32 bytes in canonical base64url.	Report it. An app calling the documented surface cannot produce this.	No
rooms: the room has ended	Error, code closed	every member of a joined Room, once it has ended for this app	The room is over here: you left, you were removed or blocked, or the rejoin window passed.	Read await room.closed for the reason, and call rooms.join(invite) for a fresh Room.	No, this Room is finished

Branch on code, never on the text: the wordings are the library’s own literals, kept here so the catalogue can find them, and a code survives a rewording. Which code each method raises is on rooms.

Broker and lifecycle

The bounded wait for a broker, a broker replaced while a call was pending, and the two rejections of an awaited relayWorker call all land here:

Message	Name or code	Surfaced by	What happened	What to do	Retryable
@fkn/lib: no broker connection within <ms>ms, so <what> could not be requested	BrokerUnreachableError	net.Socket#connect, net.Server#listen, dgram.Socket#bind, and anything else built on apiWithin from @fkn/lib/api	No broker connection settled within the deadline: 8000 ms, and once any call has missed it, every later call waits only 1000 ms.	Use apiWithin(what) wherever the caller owns a socket, a timer or a UI: it is the bounded alternative to apiPromise, which never rejects and parks forever in a realm with no broker. See Connection and lifecycle.	Yes
FKN: the broker was replaced while this call was pending; retry it	Error	any call in flight when the broker document is replaced (its update flow reloads the broker frame)	A call is bound to the broker connection it started on. When that document is replaced, pending calls are rejected rather than left to hang silently; the new connection is already routed.	Match message.startsWith('FKN: the broker was replaced') and retry once.	Yes, and the message says so
FKN @fkn/lib: relayWorker must be called from the main thread	Error	relayWorker	No window.	Call it from the page.	No
FKN @fkn/lib: relayWorker found no FKN transport in this realm	Error	relayWorker	This realm has neither a mounted broker frame nor a MessagePort granted by a parent FKN realm.	Import the library on a page that mounts the broker frame before calling relayWorker.	Yes, once the transport is up

connection and lifecycle lists the calls that wait with no deadline of their own.

Declared but not reachable

@fkn/lib 0.9.28 declares four errors that no routed call reaches. They are listed here so that you do not write a handler for them:

Message	Name or code	Why it cannot fire
The FKN WebExtension is installed but too old for this page: it speaks ABI <abi> and this page needs at least <required>. Updating the extension fixes this.	ExtensionOutdatedError	It is thrown only when the extension ABI is below the required one, and the required ABI is 0 in this release while every parsed value is clamped to 0 or more, so the comparison is never true.
The FKN WebExtension does not support "<operation>" (ABI <abi>). Updating the extension may add it.	ExtensionOperationUnsupportedError	The class is exported but nothing in the library constructs it; supportsOperation is exported for callers to branch on and no code path throws on its false.
Locator operation not supported on the cloud backend: <operation>	LocatorUnsupportedError	The cloud backend's set of unsupported operations is empty, so the guard before every call never matches, and the render proxy registers videoElement as well, so nothing refuses it either.
The FKN desktop app is not connected, desktop.<name> is unavailable	Error	No automatic routing reaches the desktop backend: desktop.available() is hardcoded false, so the root fetch never falls to it, and only a direct desktop.* call sees the throw.

The two classes are still exported, so a catch that names them type-checks and never runs. Only a direct desktop.* call sees the desktop row, as backends explains.