tursodatabase/turso · error · Error

transactionAsync is not supported with remoteWritesExperimen

Error message

transactionAsync is not supported with remoteWritesExperimental yet; use the deprecated transaction() for now

What it means

The vite promise wrapper overrides transactionAsync() with the same restriction as the turbopack build: when the database runs with remoteWritesExperimental, transactions execute on the remote server and no local connection exists to pass as a Transaction handle, so the override throws as soon as #remoteWriter is set. The doc comment points users at the deprecated transaction() whose override understands remote writes.

Source

Thrown at bindings/javascript/sync/packages/wasm/promise-vite-dev-hack.ts:333

        Object.defineProperties(properties.immediate.value, properties);
        Object.defineProperties(properties.exclusive.value, properties);
        return properties.default.value as TransactionFunction<F>;
    }

    /**
     * Returns a function that executes the given function in a transaction
     * on a connection owned for the whole BEGIN..COMMIT window; the callback
     * receives a {@link Transaction} handle as its first argument.
     *
     * Not supported together with {@link DatabaseOpts.remoteWritesExperimental}
     * yet: remote-writes transactions run on the remote server and have no
     * local connection to hand out.
     */
    override transactionAsync<F extends (txn: Transaction, ...args: any[]) => Promise<any>>(
        fn: F,
    ): AsyncTransactionFunction<F> {
        if (this.#remoteWriter) {
            throw new Error(
                "transactionAsync is not supported with remoteWritesExperimental yet; use the deprecated transaction() for now",
            );
        }
        return super.transactionAsync(fn);
    }

    /**
     * close the database and relevant files
     */
    async close() {
        if (this.#remoteWriter) {
            await this.#remoteWriter.close();
        }
        if (this.#engine != null) {
            if (this.name != null && this.#worker != null) {
                await Promise.all([
                    unregisterFileAtWorker(this.#worker, this.name),
                    unregisterFileAtWorker(this.#worker, `${this.name}-wal`),

View on GitHub (pinned to bad083fafb)

Solutions

Use `db.transaction(fn)` — in remote-writes mode its override wraps the callback in remote BEGIN..COMMIT correctly
Gate the choice on the database options: transactionAsync only when remoteWritesExperimental is falsy
If the Transaction handle is required, disable remoteWritesExperimental and use local writes with push()

Example fix

// before
const db = new Database("app.db", { url, authToken, remoteWritesExperimental: true });
const tx = db.transactionAsync(async (txn) => { /* ... */ }); // throws

// after
const db = new Database("app.db", { url, authToken, remoteWritesExperimental: true });
const tx = db.transaction(async () => { /* ... */ }); // remote BEGIN..COMMIT

Defensive patterns

Strategy: validation

Validate before calling

// Choose the transaction API from the config you own
const remoteWrites = !!opts.remoteWritesExperimental;
const db = new Database(path, opts);

const tx = remoteWrites
  ? db.transaction(fn)        // remote BEGIN..COMMIT
  : db.transactionAsync(fn); // local Transaction handle

Prevention

Centralize transaction creation in one helper shared by the app
Document at the helper boundary why remote writes exclude transactionAsync
Re-evaluate when the library adds transactionAsync support for remote writes

When it happens

Trigger: `new Database(path, { url, authToken, remoteWritesExperimental: true })` followed by `db.transactionAsync(async (txn) => { ... })`; shared app code that picks transactionAsync for its nicer ergonomics running against a remote-writes-enabled database.

Common situations: Adopting remote writes in an existing vite dev-server app that used transactionAsync; monorepos where one codebase serves both local-sync and remote-writes deployments; following newer transactionAsync documentation while the database opts enable remoteWritesExperimental.

Related errors

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/f856c3eae2164ea7. Report an issue: GitHub.