From 119e9cebd3f708b6f6aceefff87e76310eb46f84 Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:39:11 +0100
Subject: [PATCH 1/2] docs: avoid async useMutation in useUploadFile example
 (#3650)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Chris Nicholas <ctnicholasdev@gmail.com>
---
 docs/pages/api-reference/liveblocks-react.mdx | 36 ++++++++++++++++---
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/docs/pages/api-reference/liveblocks-react.mdx b/docs/pages/api-reference/liveblocks-react.mdx
index 72dd1cc01f..fac50cc592 100644
--- a/docs/pages/api-reference/liveblocks-react.mdx
+++ b/docs/pages/api-reference/liveblocks-react.mdx
@@ -3776,14 +3776,42 @@ Returns a function that uploads a file to the current room. The function
 resolves to a [`LiveFile`](/docs/api-reference/liveblocks-client#LiveFile) that
 can be stored in Storage.
 
+Because [`useMutation`](/docs/api-reference/liveblocks-react#useMutation)
+doesn’t support async callbacks, await the upload outside of the mutation, then
+pass the resulting `LiveFile` into it.
+
 ```tsx
+import { useCallback } from "react";
 import { useMutation, useUploadFile } from "@liveblocks/react/suspense";
+import type { LiveFile } from "@liveblocks/client";
+
+function UploadFile() {
+  const uploadFile = useUploadFile();
+
+  const setFile = useMutation(({ storage }, file: LiveFile) => {
+    storage.set("file", file);
+  }, []);
 
-const uploadFile = useUploadFile();
+  const handleFile = useCallback(
+    async (file: File) => {
+      const liveFile = await uploadFile(file);
+      setFile(liveFile);
+    },
+    [uploadFile, setFile]
+  );
 
-const setFile = useMutation(async ({ storage }, file: File) => {
-  storage.set("file", await uploadFile(file));
-}, []);
+  return (
+    <input
+      type="file"
+      onChange={(e) => {
+        const file = e.currentTarget.files?.[0];
+        if (file) {
+          handleFile(file);
+        }
+      }}
+    />
+  );
+}
 ```
 
 The function accepts the same arguments and returns the same result as

From 07f27779ddb4be06809efb1c462f03e67a23c456 Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 7 Aug 2026 13:03:20 +0200
Subject: [PATCH 2/2] docs: note that useMutation doesn't support async
 functions (#3651)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 docs/pages/api-reference/liveblocks-react.mdx | 31 +++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/pages/api-reference/liveblocks-react.mdx b/docs/pages/api-reference/liveblocks-react.mdx
index fac50cc592..bcb6d7ab73 100644
--- a/docs/pages/api-reference/liveblocks-react.mdx
+++ b/docs/pages/api-reference/liveblocks-react.mdx
@@ -3777,8 +3777,9 @@ resolves to a [`LiveFile`](/docs/api-reference/liveblocks-client#LiveFile) that
 can be stored in Storage.
 
 Because [`useMutation`](/docs/api-reference/liveblocks-react#useMutation)
-doesn’t support async callbacks, await the upload outside of the mutation, then
-pass the resulting `LiveFile` into it.
+[doesn’t support async callbacks](/docs/api-reference/liveblocks-react#useMutation-async),
+await the upload outside of the mutation, then pass the resulting `LiveFile`
+into it.
 
 ```tsx
 import { useCallback } from "react";
@@ -4120,6 +4121,32 @@ return <button onClick={deleteSelectedShapes} />;
 Mutations are automatically batched, so when using `useMutation` there’s no need
 to use `useBatch`, or call `room.batch()` manually.
 
+#### Doesn’t work with async functions [#useMutation-async]
+
+Because mutations are batched with
+[`room.batch`](/docs/api-reference/liveblocks-client#Room.batch), which
+[cannot take an `async` function](/docs/api-reference/liveblocks-client#Doesn't-work-with-async-functions),
+the mutation function passed to `useMutation` cannot be `async` either.
+
+```tsx
+// ❌ Won’t work
+const updateFill = useMutation(async ({ storage }) => {
+  const fill = await fetchColor();
+  storage.get("shapes").get("circle1").set("fill", fill);
+}, []);
+
+// ✅ Will work
+const updateFill = useMutation(({ storage }, fill: string) => {
+  storage.get("shapes").get("circle1").set("fill", fill);
+}, []);
+
+// …with the async work happening outside of the mutation
+const handleClick = useCallback(async () => {
+  const fill = await fetchColor();
+  updateFill(fill);
+}, [updateFill]);
+```
+
 #### ESLint rule [#useMutation-lint-rule] [@keywords=["exhaustive-deps", "additionalHooks", "eslint-plugin-react-hooks"]]
 
 If you are using ESLint in your project, and are using