diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 15bb998be9bf1..3a1bde32700c1 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -46,6 +46,13 @@ direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_
 🎉
 ```
 
+> **Note:** On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause `nix-shell` to fail to build or run `coder`. If you see `error: creating directory` when attempting to run, build, or test, adding one line to your `.envrc` should fix the problem:
+
+```shell
+use nix
+mkdir -p "$TMPDIR"
+```
+
 Alternatively if you do not want to use nix then you'll need to install the need
 the following tools by hand: