diff --git a/platform/ios/platform/macos/README.md b/platform/ios/platform/macos/README.md
index d90b777ff..3b3e1e170 100644
--- a/platform/ios/platform/macos/README.md
+++ b/platform/ios/platform/macos/README.md
@@ -1,5 +1,8 @@
 # MapLibre GL Native for macOS
 
+> **Note**  
+> https://github.com/maplibre/maplibre-gl-native/pull/995 introduced OpenGL ES 3.0 shaders which are not supported by macOS without workarounds. That means that while the [Metal backend implementation](https://github.com/maplibre/maplibre-gl-native/blob/main/design-proposals/2022-11-29-metal-port.md) is underway, builds from the `main` branch will not work on macOS. Use the `opengl-2` branch in the meantime.
+
 [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/macos-ci/badge.svg)](https://github.com/maplibre/maplibre-gl-native/actions/workflows/macos-ci.yml) [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/macos-release/badge.svg)](https://github.com/maplibre/maplibre-gl-native/actions/workflows/macos-release.yml)
 
 Put interactive, scalable world maps into your native Cocoa application with MapLibre GL Native for macOS.