Errors
What each error means, whether the write may have happened, and what to do next.
Every error Minnow throws answers three questions: may the operation have happened anyway, is
repeating the call sound, and is the connection still usable. classifyError() from
@minnowdb/core answers them for any error, including one rehydrated across the worker or the
OPFS follower hop and the platform's own QuotaExceededError:
import { classifyError } from "@minnowdb/core";
try {
await client.insert("orders", order);
} catch (error) {
const { kind, mayHavePublished, retry, connectionUsable } = classifyError(error);
if (mayHavePublished)
await reconcileBySaleId(sale.id); // never blindly resend
else if (retry === "safe") await backoffAndRetry();
if (!connectionUsable) await client.reopen();
}The matrix
| Kind | Errors | May have published | Retry | Connection usable |
|---|---|---|---|---|
unknown-outcome | DatabaseWorkerOutcomeUnknownError, OpfsUncertainOutcomeError, StorageUnresponsiveError — all extend UnknownOutcomeError | yes | after reconciling | see below |
connection-lost | DatabaseWorkerTimeoutError, DatabaseWorkerFailedError, StorageConnectionClosedError — all extend ConnectionLostError | no | never on this client | no |
conflict | WriteConflictError, SchemaConflictError, TableRecordConflictError, TransactionRecordConflictError, lease, compaction, collection, temp-owner, index-build, and snapshot-import conflicts, TableInUseError, OpfsDatabaseInUseError | no | as is | yes |
rejected | UniqueConstraintError, UniqueKeyConflictError, UniqueIndexCoverageError, MissingKeyError, UnknownTableError, SqlCompileError, CompactionJobCancelledError, any TypeError, RangeError, SyntaxError | no | never as written | yes |
transient | WriteNotPublishedError, OpfsCoordinationError, DatabaseReadBacklogError, MaintenanceBacklogError, CompactionBacklogError, LiveQueryLimitError, LeaseExpiredError, TransactionExpiredError, StorageUpgradeBlockedError (and its IndexedDbSchemaUpgradeBlockedError form), VisibleSegmentCursorStaleError | no | with backoff | yes (see below) |
resource | QuotaExceededError, StorageResourceLimitError, BlockReadBatchTooLargeError, CompactionMemoryBudgetError, CompactionWriteAmplificationError | no | after freeing space (retry: "after-reconcile") | yes |
corruption | StorageCorruptionError, StorageFormatVersionError | no | never | yes |
cancelled | An AbortError from the caller's own signal | no | as is | yes |
other | Anything else — a plain Error, a QueryMemoryBudgetError, a platform error the engine does not classify | no | never as written | yes |
An unknown-outcome error is the one case where "the call threw" does not mean "nothing
happened". The engine never replays a mutation on its own; reconcile a stable identity (a sale
id, a revision) before deciding whether to send it again. Its cause tells you whether the
connection survived: a mutation cancelled by its own signal leaves the connection usable, one
rejected because the worker fell silent does not.
The engine keeps that uncertainty honest in both directions. A commit whose acknowledgement was
lost reads its own record back, several times if the store is still recovering, and reports the
commit as success when the record says it landed; when every read fails, the error you get is
still the UnknownOutcomeError (with the read failure as its cause), never a conflict or
transient error that would call a retry safe. And a storage step that cannot publish — a row-id
or auto-increment reservation, a lease renewal, a journal write before the commit — that loses its
acknowledgement is reported as WriteNotPublishedError: nothing of the write is visible, so
repeating it is safe. Its cause is the underlying uncertain error, and
classifyError(error).connectionUsable reads that cause, so an unresponsive store still reports
the connection as finished.
Error identity across the worker
classifyError and instanceof work on an error that crossed the worker boundary (or the OPFS
follower hop) because the client rebuilds it from the literal name the engine stamps on every
error instance, not from the class's own identifier. A bundler that minifies class names — the
default for every production build — therefore does not affect error identity: no keepNames or
keep_classnames setting is needed. classifyError also falls back to that name when the
prototype is not its own class, which covers an application bundle that ended up with two
copies of @minnowdb/core.
Losing and reopening a connection
DatabaseWorkerTimeoutError and DatabaseWorkerFailedError are fatal for the client: every
later call throws the same error. The client reports the loss once through onConnectionLost,
and reopen() puts a fresh worker behind the same client with the same store and options:
const client = new MinnowDatabaseClient(() => new Worker(workerUrl, { type: "module" }), {
store: { kind: "opfs", name: "shop" },
onConnectionLost: () => void client.reopen().then(rebuildHandles),
});Handles from before the loss — write scopes, live sets, cursors, buffered writers — belonged to the old worker and must be recreated. A mutation that was in flight was already reported as an unknown outcome.
A store that stops answering
StorageUnresponsiveError means an IndexedDB wait exceeded its silence budget (thirty seconds by
default). On an open connection with work outstanding, native request and transaction responses
(success, error, complete and abort), and awaited request/transaction settlements, reset
that budget. Bulk requests count without being awaited separately; so do cursor continuation and
prevented request errors. A new request alone does not count as a response.
versionchange starts superseding and closing instead of resetting that clock. An open request's
blocked notification uses the separate open/upgrade wait policy. Neither notification proves
that pending data requests are answering.
The known cause is a worker terminated with worker.terminate() while one of its IndexedDB
transactions was still queued — behind another of its own, or behind another tab's write that
waits on it. Safari and other WebKit browsers can keep that transaction registered after the
worker is gone. While it is registered, every transaction that overlaps it blocks, in every tab,
including connections opened afterwards. Opening the database can report it too, since the
open's first read waits behind the stuck transaction: the worker keeps reporting while the store
opens, so ready() fails with StorageUnresponsiveError rather than a worker timeout.
Close the site's tabs, then open the site again. reopen() is not enough: a new worker opens
the same wedged database. Reloading the tab that ran the dead worker does not always release the
transaction either; closing that tab does. Let the engine terminate workers for you —
close({ terminateWorker: true }) disposes the store first — and treat a write that was in
flight as an unknown outcome.
Background failures that belong to no call — an uncaught exception in the worker, a failed
checkpoint, an election that threw — are not errors on any promise. They arrive through
onWorkerError, described under Workers.