{"record":{"id":"59d9621557e98b30","repo":"tursodatabase/turso","slug":"transactionasync-is-not-supported-with-remotewrite","errorCode":null,"errorMessage":"transactionAsync is not supported with remoteWritesExperimental yet; use the deprecated transaction() for now","messagePattern":"transactionAsync is not supported with remoteWritesExperimental yet; use the deprecated transaction\\(\\) for now","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/sync/packages/native/promise.ts","lineNumber":318,"sourceCode":"        Object.defineProperties(properties.immediate.value, properties);\n        Object.defineProperties(properties.exclusive.value, properties);\n        return properties.default.value as TransactionFunction<F>;\n    }\n\n    /**\n     * Returns a function that executes the given function in a transaction\n     * on a connection owned for the whole BEGIN..COMMIT window; the callback\n     * receives a {@link Transaction} handle as its first argument.\n     *\n     * Not supported together with {@link DatabaseOpts.remoteWritesExperimental}\n     * yet: remote-writes transactions run on the remote server and have no\n     * local connection to hand out.\n     */\n    override transactionAsync<F extends (txn: Transaction, ...args: any[]) => Promise<any>>(\n        fn: F,\n    ): AsyncTransactionFunction<F> {\n        if (this.#remoteWriter) {\n            throw new Error(\n                \"transactionAsync is not supported with remoteWritesExperimental yet; use the deprecated transaction() for now\",\n            );\n        }\n        return super.transactionAsync(fn);\n    }\n\n    /**\n     * close the database\n     */\n    override async close(): Promise<void> {\n        if (this.#remoteWriter) {\n            await this.#remoteWriter.close();\n        }\n        await super.close();\n        if (this.#engine != null) {\n            this.#engine.close();\n        }\n    }","sourceCodeStart":300,"sourceCodeEnd":336,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/javascript/sync/packages/native/promise.ts#L300-L336","documentation":"transactionAsync() hands the callback a Transaction handle bound to a connection owned for the whole BEGIN..COMMIT window. Under remoteWritesExperimental, transactions run on the remote server via RemoteWriter and there is no local connection to hand out, so the override deliberately throws when a remote writer is installed. The error tells you to use the (deprecated) transaction() wrapper, whose callback runs against the database while BEGIN/COMMIT are sent to the remote.","triggerScenarios":"Calling db.transactionAsync(fn) on a Database constructed with remoteWritesExperimental: true and a URL; generic ORM/data-layer code that standardizes on transactionAsync across sync and non-sync deployments.","commonSituations":"Enabling the experimental remote-writes feature in an app already built on transactionAsync; shared middleware that always uses the async-transaction API; upgrading the sync package and hitting the new guard.","solutions":["Switch that call site to db.transaction(fn), which is supported with remoteWritesExperimental.","Branch on your remote-writes flag: use transaction() when enabled, transactionAsync() otherwise.","Track upstream support — the doc comment marks the combination as unsupported 'yet', so re-test after upgrades."],"exampleFix":"// before\nconst runTxn = db.transactionAsync(fn); // db opened with remoteWritesExperimental: true\n\n// after\nconst runTxn = remoteWritesEnabled\n  ? db.transaction(fn)      // remote-writes transactions run on the server\n  : db.transactionAsync(fn);","handlingStrategy":"validation","validationCode":"// choose the transaction API based on how the DB was opened\nconst useTxnAsync = !remoteWritesEnabled;\nconst runTxn = useTxnAsync ? db.transactionAsync(fn) : db.transaction(fn);","typeGuard":null,"tryCatchPattern":"try {\n  return await db.transactionAsync(fn)(...args);\n} catch (e) {\n  if (e instanceof Error && /transactionAsync is not supported/.test(e.message)) {\n    return await db.transaction(fn)(...args); // remote-writes path\n  }\n  throw e;\n}","preventionTips":["Record whether remoteWritesExperimental was enabled and branch on it for transaction APIs.","Keep a feature-compatibility matrix in tests: transaction/transactionAsync x remoteWrites on/off.","Re-read the deprecation notes after package upgrades — transactionAsync support for remote writes may land later."],"tags":["transaction","remote-writes","unsupported-combination","javascript"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}