add cgroup memory to troubleshooting

EdwardAngert · EdwardAngert · commit 20477fd03350 · 2025-03-14T03:56:04.000Z
diff --git a/docs/install/index.md b/docs/install/index.md
@@ -68,6 +68,62 @@ To log in to an existing Coder deployment:
 coder login https://coder.example.com
 ```
 
+## Troubleshooting
+
+### Unable to query ContainerMemory
+
+When you query `ContainerMemory` and encounter the error:
+
+```shell
+open /sys/fs/cgroup/memory.max: no such file or directory
+```
+
+This error mostly affects Raspbery Pi OS, but might also affect older Debian-based systems as well.
+
+<details><summary>Add `cgroup_memory=1 cgroup_enable=memory` to `cmdline.txt`:</summary>
+
+1. Confirm the list of existing cgroup controllers doesn't include `memory`:
+
+   ```console
+   $ cat /sys/fs/cgroup/cgroup.controllers
+   cpuset cpu io pids
+
+   $ cat /sys/fs/cgroup/cgroup.subtree_control
+   cpuset cpu io pids
+   ```
+
+1. Add cgroup entries to `cmdline.txt` in `/boot/firmware` (or `/boot/` on older Pi OS releases):
+
+   ```text
+   cgroup_memory=1 cgroup_enable=memory
+   ```
+
+   You can use `sed` to add it to the file for you:
+
+   ```bash
+   sudo sed -i '$s/$/ cgroup_memory=1 cgroup_enable=memory/' /boot/firmware/cmdline.txt
+   ```
+
+1. Reboot:
+
+   ```bash
+   sudo reboot
+   ```
+
+1. Confirm that the list of cgroup controllers now includes `memory`:
+
+   ```console
+   $ cat /sys/fs/cgroup/cgroup.controllers
+   cpuset cpu io memory pids
+
+   $ cat /sys/fs/cgroup/cgroup.subtree_control
+   cpuset cpu io memory pids
+   ```
+
+Read more about cgroup controllers in [The Linux Kernel](https://docs.kernel.org/admin-guide/cgroup-v2.html#controlling-controllers) documentation.
+
+</details>
+
 ## Next steps
 
 - [Quickstart](../tutorials/quickstart.md)
