Handling errors

The broker is the connection your page holds into FKN. A call that reaches it is answered in another JavaScript context, so the error you catch is only what survived the trip back. This page covers which fields of an error survive, which two errors keep a class, how to test the rest, and which failures are worth retrying.

See also

• every error
• how it works
• TypeScript
• limits and timeouts

What crosses a realm

The broker runs in another realm. A realm is one JavaScript execution context, such as a window or a worker. The library mounts a hidden fkn.app iframe, the broker frame, and behind that frame runs a shared worker, the data plane, where the call is served.

An error thrown in the data plane crosses two hops before you catch it: one into the broker frame and one into your realm. Each hop carries name, message, stack and cause and nothing else. The hops are described under how it works.

A read while the storage api is not answering shows what arrives:

app.ts

try {
  await cloud.fs.promises.readFile('library/catalog.json', 'utf8')
} catch (error) {
  const { name, message, code } = error as Error & { code?: string }
  name // 'Error', so there is no class to test, only the sentence
  message // 'storage: api unreachable', the prefix you match
  code // undefined, set beside that sentence in the data plane and gone by here
}

Three things follow from that:

• instanceof does not work across a hop. The class the broker threw is not a constructor in your realm.
• A custom code does not arrive. The data plane sets one beside storage: api unreachable, and only the message prefix reaches you.
• name survives. The FKN browser extension and the locators identify their refusals by it.

An error created in your own realm keeps every field. BrokerUnreachableError is a class, so you can test it with instanceof. The library throws it when no broker connection settles within the 8,000 ms broker deadline, or within 1,000 ms once any call in the realm has already missed that deadline.

The ENOENT family on the node-style members of fs, opfs and cloud.fs carries a real code. So does PackagesError, which is a type rather than a class, so its code is the field to test. Both are listed under TypeScript. opfs never reaches the broker, so its errors are ordinary same-realm errors, as described under entry points.

Two errors keep a class

StorageLockedError and StorageNotFoundError are the two exceptions. The library catches every cloud.fs read and write rejection on your side and, for those two, throws a fresh error of its own class with a code. That step is the re-mint.

StorageLockedError replaces an error whose message carries the broker’s fkn:e2e-locked prefix. StorageNotFoundError replaces an error whose code already reads FKN_STORAGE_NOT_FOUND, or, failing that, one whose message reads Not found or ends in (404).

A missing file is reported in two wordings. When the api refuses to presign a path that has no committed row, the message is Not found. When the presign succeeds and the object itself answers 404, the message is storage: read failed (404).

An app that matched only the first wording treated a missing backup as a transient failure and retried forever. isNotFound covers both:

app.ts

import { cloud } from '@fkn/lib'
import { isNotFound, StorageLockedError } from '@fkn/lib/cloud/fs'

try {
  await cloud.fs.promises.readFile('backup/library.bin')
} catch (error) {
  isNotFound(error) // true for both 'Not found' and 'storage: read failed (404)'
  error instanceof StorageLockedError // false, locked is its own class and never reads as absence
}

isNotFound answers true for both wordings. StorageLockedError carries storage locked: this account stores encrypted data, unlock it from the FKN card or unlock(), a sentence that matches neither on purpose. The difference matters: a path with nothing at it is safe to write a first backup to, and a path you could not read is not.

The order to test in

Test in the order the errors were created. The two classes come first, then the message prefixes, then the names, and last the one class that never crossed a hop:

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, minted in your realm
  if (isNotFound(error)) return null // start empty
  if (error instanceof StorageLockedError) return promptUnlock() // ask, then read again

  // the rest of the broker's errors, by 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() // retry later
  if (message.startsWith('FKN: the broker was replaced')) return retryOnce() // routed to the new broker already

  // locators and frames, by name, through the guards
  if (isLocatorDenied(error)) return explainRefusal() // a gate said no
  if (isTerminalError(error)) return giveUp() // retrying changes nothing

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

  // the broker deadline, a class minted here
  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

The two classes come first because they carry the only code a cloud.fs rejection can be trusted to have. The prefix branch compares sentences because the E2E_* constants from @fkn/lib/messages and the two fixed prefixes are exactly what the broker sends. The constants are described under encryption, and every message has a row on every error.

Note

STORAGE_UNREACHABLE, exported beside the E2E_* constants, is the code FKN_API_UNREACHABLE. That code never crosses the hop, so the example leaves it unimported and tests the sentence instead.

A refusal neither guard matches

The consent sheet is the prompt the extension shows before an action that needs the user’s approval. When the user refuses there, the extension rejects with Permission denied: <key> (<scope>) under the name PermissionDeniedError. Neither locator guard looks for that name:

app.ts

try {
  await frame.locator('#play').click({ reason: 'Start the trailer' })
} catch (error) {
  const { name, message } = error as Error
  isLocatorDenied(error) // false, even though the user refused
  isTerminalError(error) // false
  name // 'PermissionDeniedError'
  message // 'Permission denied: act.click (#play)'
}

The refusal is still terminal. The consent sheet raises it before the retry loop starts, but only the name test above tells you so. The keys and scopes are described under permissions and consent.

The name with no constant

@fkn/lib re-exports the constants LOCATOR_DENIED, LOCATOR_ERROR and LOCATOR_UNSUPPORTED and the guards isLocatorDenied, isLocatorUnsupported and isTerminalError. It does not export LOCATOR_INVALID, isLocatorInvalid or locatorInvalidError. isTerminalError still matches the invalid name. The guard reads nothing but the name, so an error built with that name is enough to show it:

app.ts

import { isLocatorInvalid } from '@fkn/lib'
Error ts(2305)  ― Module '"@fkn/lib"' has no exported member 'isLocatorInvalid'.
import { isTerminalError } from '@fkn/lib'

const invalid = Object.assign(new Error('fetch: url must be a string'), { name: 'LocatorInvalidError' })
isTerminalError(invalid) // true, the invalid name stops the loop like the other two

Use the guard rather than comparing against a name whose constant you cannot import. The locator errors are described under locators and actions.

What a timeout says

A locator action retries every failed attempt until its deadline, which is 30,000 ms unless you pass timeout. It then rethrows the last attempt’s error. For a missing element that error is No elements found:

app.ts

try {
  await frame.locator('h1').textContent()
} catch (error) {
  const { name, message } = error as Error
  message // 'No elements found', after 30 seconds
  name // 'LocatorError', the last attempt's error rather than a timeout
}

Locator timeout (30000ms): textContent appears only when no attempt failed before the deadline. A handler that waits for the word timeout will not see it after a missing element.

unlink() skips the re-mint

The re-mint wraps cloud.fs reads and writes only. The deletes, unlink, rm and rmdir, are not wrapped, in the promise form and the callback form alike. Deleting a missing path therefore rejects with the api’s own Not found, and isNotFound answers false:

app.ts

import { cloud } from '@fkn/lib'
import { isNotFound } from '@fkn/lib/cloud/fs'

try {
  await cloud.fs.promises.unlink('backup/library.bin')
} catch (error) {
  const { message } = error as Error
  message // 'Not found', the api's own sentence
  isNotFound(error) // false, unlink does not run the re-mint
}

A recursive rm goes further: it swallows the failure of every object under the path and reports nothing at all. For a delete, match the message or treat any failure as best effort. Deletes are described under storage.

Which failures are worth retrying

One row per group of every error, with the test for that group and whether the same call can succeed later:

Group	What to test	Retry
Fetch	a refusal from the library or the extension rejects, so wrap the call. A refusal from the proxy, the server cloud.fetch sends a request through, arrives as a resolved Response, so check response.ok and the body’s error	a 429 or a 502 in the body, or no proxy being available, never a refused target
Sockets	an argument or state refusal throws at the call, and a connect, bind or listen failure arrives as the message prefix on the error event	a timed-out connect or a capacity ceiling, never a refused address
Storage	isNotFound(), instanceof StorageLockedError, then the storage: prefix	unreachable and Concurrent update, retry, locked after unlock(), never absence
Encryption	the three E2E_* prefixes, then the api’s own sentences	never on fkn:e2e-stale-epoch or fkn:e2e-integrity, a write refused with Superseded key at once, and one refused with This account has no encryption keys yet after re-enrolling
Frames	the message prefix, then isTerminalError()	a timed-out handshake or goto, never a refusal
Locators	isLocatorDenied(), isTerminalError(), then error.name	not for a plain LocatorError, which the loop already retried, and not for a terminal name, which was never retried and will not change
Permissions	error.name === 'PermissionDeniedError'	only through the user
Packages	error.code	a timeout or an unavailable, and an invalid only after fixing the argument it names
Broker	instanceof BrokerUnreachableError, then the FKN: the broker was replaced prefix	the class after a wait, and the replaced broker once. A relayWorker refusal needs the realm fixed rather than a retry

Several rows describe an integration working as intended, such as a refusal at the consent sheet or a missing first backup. Handle those as answers rather than failures.

Errors you might see

The six broker and lifecycle rows, each with its cause and its fix:

Message	What happened	What to do
@fkn/lib: no broker connection within <ms>ms, so <what> could not be requested	No broker connection settled inside the deadline of 8,000 ms, or 1,000 ms after a miss. The usual cause is a worker nobody relayed.	Call await relayWorker(worker, { unregisterSignal }) from the page, as shown under workers.
FKN: the broker was replaced while this call was pending; retry it	An update of the shell, the FKN surface that can update and reload the page, reloaded the broker frame while a call was in flight.	Retry once. The replacement is described under errors and lifecycle.
FKN @fkn/lib: relayWorker must be called from the main thread	relayWorker ran inside a worker.	Call it from the page.
FKN @fkn/lib: relayWorker found no FKN transport in this realm	This realm holds neither a mounted broker frame nor a port from a parent FKN realm.	Import the library on a page that mounts the broker frame first, as described under how it works.
storage: api unreachable	The storage api never answered at all, which is different from the api answering with an error.	Keep the local copy and retry later.
webvpn: socket capacity reached	The relay, the server that holds the real socket for net and dgram, reached a capacity ceiling.	Close a socket this app holds to free a slot. The ceilings are listed under limits and timeouts.

Every other message has a row on every error. The calls that wait with no deadline are listed on errors and lifecycle.