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, what a call the extension never finished rejects with, 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: connect the app again to open encrypted data, 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 a row there, the extension rejects with Permission denied: <category> on <site> (<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
  isPermissionDenied(error) // true, the one guard that reads this name
  name // 'PermissionDeniedError'
  message // 'Permission denied: interaction on example.org (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 message names the row the user answered first and the concrete call in brackets, and both are described under permissions and consent.

The three terminal names

@fkn/lib re-exports the constants LOCATOR_DENIED, LOCATOR_ERROR, LOCATOR_INVALID and LOCATOR_UNSUPPORTED and the guards isLocatorDenied, isLocatorInvalid, isLocatorUnsupported and isTerminalError. LOCATOR_INVALID and isLocatorInvalid are exported since @fkn/lib 0.9.42. isTerminalError matches the three names that stop the retry loop. Each guard reads nothing but the name, so an error built with that name is enough to show it:

app.ts

import { isLocatorInvalid, isTerminalError, LOCATOR_INVALID } from '@fkn/lib'

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

Use the guards rather than comparing names by hand. The locator errors are described under locators and actions.

What a timeout says

Every call with a deadline ends at it with a TimeoutError, exported from the root, named 'TimeoutError' and minted in your realm, so instanceof works: a locator action, goto, evaluate, addScriptTag and clearCookies. Its message is what the call reported at that moment, unchanged. A locator action retries every failed attempt until its deadline, which is 30,000 ms unless you pass timeout, so for a missing element the message is No elements found, and the last attempt’s error is the cause:

app.ts

try {
  await frame.locator('h1').textContent()
} catch (error) {
  if (!(error instanceof TimeoutError)) throw error
  error.message // 'No elements found', after 30 seconds
  const cause = error.cause as Error
  cause.name // 'LocatorError', the last attempt's error
}

Locator timeout (30000ms): textContent is the message only when no attempt failed before the deadline, and then there is no cause. A handler that waits for the word timeout in the message will not see it after a missing element, so test the class or the name.

A call the extension never finished

Chrome stops the FKN extension’s service worker whenever it has been idle for a while. The calls that run there are extension.fetch and the root fetch on the extension path, cookies.get, the header rules, and attachFrame and goto() on cookies: 'native'. From the next FKN extension store release, the first after 0.1.54, one of them that a stop cuts off rejects with an Error named BackgroundStoppedError, either before it resolved or, for a fetch, while its body was still arriving, and the next call is answered by the restarted worker. Through 0.1.54 nothing rejects: such a call made after a stop stays pending until the page reloads.

@fkn/lib 0.9.43 exports the name as BACKGROUND_STOPPED and the guard isBackgroundStopped, which reads nothing but the name, so a handler written now already works on that release:

app.ts

import { extension, isBackgroundStopped } from '@fkn/lib'

const load = async (): Promise<string> => {
  const response = await extension.fetch('https://example.org/api/catalog.json')
  return response.text() // a body the stop cut off rejects here, under the same name
}

const catalog = await load().catch((error) => {
  if (!isBackgroundStopped(error)) throw error
  return load() // a GET is harmless to run twice, and the restarted worker answers it
})

The call may or may not have run, so the extension never sends it again, and a retry is yours to decide. Repeat a read like the GET above, and find out what happened before repeating a call that changes something, such as a POST. Both messages are on every error.

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	instanceof FrameWindowBlockedError and FrameWindowRefusedError for a window, instanceof TimeoutError for a deadline, the message prefix, then isTerminalError()	a timed-out handshake or goto, and a blocked window from a fresh click, never a refused target or option
Locators	isLocatorDenied(), isTerminalError(), instanceof TimeoutError, then error.name	a TimeoutError once the page had time to settle, since the loop already retried each attempt inside it, and never 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, and isBackgroundStopped() for a call into the extension	the class after a wait, the replaced broker once, and a stopped extension call when running it twice is harmless. 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 seven 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.
the FKN extension's background stopped before it answered	BackgroundStoppedError: Chrome stopped the extension’s idle worker while a call was out. Raised from the next extension store release, the first after 0.1.54.	Retry with your own call when running it twice is harmless, see a call the extension never finished.
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.