diff --git a/android/filament-android/src/main/java/com/google/android/filament/Engine.java b/android/filament-android/src/main/java/com/google/android/filament/Engine.java
index 70622cc7f8..85580d2739 100644
--- a/android/filament-android/src/main/java/com/google/android/filament/Engine.java
+++ b/android/filament-android/src/main/java/com/google/android/filament/Engine.java
@@ -609,6 +609,9 @@ public class Engine {
      * all commands to this point are executed. Note that this doesn't guarantee that the
      * hardware is actually finished.
      *
+     * <p><b>Use with caution on macOS.</b> Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.</p>
+     *
      * <p>This is typically used right after destroying the <code>SwapChain</code>,
      * in cases where a guarantee about the SwapChain destruction is needed in a timely fashion,
      * such as when responding to Android's
diff --git a/android/filament-android/src/main/java/com/google/android/filament/Fence.java b/android/filament-android/src/main/java/com/google/android/filament/Fence.java
index f620216428..56786e8f19 100644
--- a/android/filament-android/src/main/java/com/google/android/filament/Fence.java
+++ b/android/filament-android/src/main/java/com/google/android/filament/Fence.java
@@ -37,6 +37,12 @@ public class Fence {
         TIMEOUT_EXPIRED
     }
 
+    /**
+     * Blocks the current thread until the Fence signals.
+     *
+     * <p><b>Use with caution on macOS.</b> Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.</p>
+     */
     public FenceStatus wait(@NonNull Mode mode, long timeoutNanoSeconds) {
         int nativeResult = nWait(getNativeObject(), mode.ordinal(), timeoutNanoSeconds);
         switch (nativeResult) {
diff --git a/filament/include/filament/Engine.h b/filament/include/filament/Engine.h
index a6296a8387..aada9458b6 100644
--- a/filament/include/filament/Engine.h
+++ b/filament/include/filament/Engine.h
@@ -358,6 +358,9 @@ public:
      * all commands to this point are executed. Note that this doesn't guarantee that the
      * hardware is actually finished.
      *
+     * \warning Use with caution on macOS. Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.
+     *
      * <p>This is typically used right after destroying the <code>SwapChain</code>,
      * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
      * timely fashion, such as when responding to Android's
diff --git a/filament/include/filament/Fence.h b/filament/include/filament/Fence.h
index f54db8737c..7c6301e7b4 100644
--- a/filament/include/filament/Fence.h
+++ b/filament/include/filament/Fence.h
@@ -58,6 +58,9 @@ public:
      *
      * Blocks the current thread until the Fence signals.
      *
+     * \warning Use with caution on macOS. Currently this may lead to deadlock on macOS because we
+     * block the GL thread when binding a Cocoa view to the GL context.
+     *
      * @param mode      Whether the command stream is flushed before waiting or not.
      * @param timeout   Wait time out. Using a \p timeout of 0 is a way to query the state of the fence.
      *                  A \p timeout value of FENCE_WAIT_FOR_EVER is used to disable the timeout.