diff --git a/source/guides/troubleshooting.md b/source/guides/troubleshooting.md
index 87a13d3f8..6df8e7060 100644
--- a/source/guides/troubleshooting.md
+++ b/source/guides/troubleshooting.md
@@ -50,3 +50,17 @@ $ nix-store --load-db < /tmp/db.dump
 This may mean you are trying to import a too large file or directory into the [Nix store](https://nix.dev/manual/nix/stable/glossary#gloss-store), or your machine is running out of resources, such as disk space or memory.
 
 Try to reduce the size of the directory to import, or run [garbage collection](https://nix.dev/manual/nix/stable/command-ref/nix-collect-garbage).
+
+## macOS update breaks Nix installation
+
+This is a [known issue](https://github.com/NixOS/nix/issues/3616).
+The [Nix installer](https://nix.dev/manual/nix/latest/installation/installing-binary) modifies `/etc/zshrc`.
+When macOS is updated, it will typically overwrite `/etc/zshrc` again.
+
+As a workaround, add the following code snippet to the end of `/etc/zshrc` and restart the shell:
+
+```bash
+if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
+  . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
+fi
+```