Engine

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

KindErrorsMay have publishedRetryConnection usable
unknown-outcomeDatabaseWorkerOutcomeUnknownError, OpfsUncertainOutcomeError, StorageUnresponsiveError — all extend UnknownOutcomeErroryesafter reconcilingsee below
connection-lostDatabaseWorkerTimeoutError, DatabaseWorkerFailedError, StorageConnectionClosedError — all extend ConnectionLostErrornonever on this clientno
conflictWriteConflictError, SchemaConflictError, TableRecordConflictError, TransactionRecordConflictError, lease, compaction, collection, temp-owner, index-build, and snapshot-import conflicts, TableInUseError, OpfsDatabaseInUseErrornoas isyes
rejectedUniqueConstraintError, UniqueKeyConflictError, UniqueIndexCoverageError, MissingKeyError, UnknownTableError, SqlCompileError, CompactionJobCancelledError, any TypeError, RangeError, SyntaxErrornonever as writtenyes
transientWriteNotPublishedError, OpfsCoordinationError, DatabaseReadBacklogError, MaintenanceBacklogError, CompactionBacklogError, LiveQueryLimitError, LeaseExpiredError, TransactionExpiredError, StorageUpgradeBlockedError (and its IndexedDbSchemaUpgradeBlockedError form), VisibleSegmentCursorStaleErrornowith backoffyes (see below)
resourceQuotaExceededError, StorageResourceLimitError, BlockReadBatchTooLargeError, CompactionMemoryBudgetError, CompactionWriteAmplificationErrornoafter freeing space (retry: "after-reconcile")yes
corruptionStorageCorruptionError, StorageFormatVersionErrornoneveryes
cancelledAn AbortError from the caller's own signalnoas isyes
otherAnything else — a plain Error, a QueryMemoryBudgetError, a platform error the engine does not classifynonever as writtenyes

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.

On this page