diff --git a/README.md b/README.md
index 6359e925e0..a11e07ef2d 100644
--- a/README.md
+++ b/README.md
@@ -20,3 +20,8 @@ Supported cloud providers:
 - 🟢 AWS (Beta)
 - [ ] Azure
 - [ ] General linux machine
+
+## Limitations
+
+- Custom template builds require Debian/Ubuntu-based base images (images that provide the apt package manager). Non-Debian images such as Alpine, CentOS/RHEL, or other distributions without apt are not supported and will fail during the template build/provisioning process. See [docs/limitations.md](docs/limitations.md) for details and suggested PR wording.
+
diff --git a/docs/limitations.md b/docs/limitations.md
new file mode 100644
index 0000000000..b08fa3781c
--- /dev/null
+++ b/docs/limitations.md
@@ -0,0 +1,23 @@
+Custom template build: Debian/Ubuntu-only base images
+===================================================
+
+Summary
+-------
+
+E2B currently requires that base images used for custom template builds are Debian/Ubuntu-based and provide the `apt` package manager. The template build and provisioning scripts assume Debian package manager behavior and Debian-style filesystem layouts; using images without `apt` (for example, Alpine, CentOS, RHEL, or other non-Debian distributions) will cause the build to fail.
+
+Why this limitation exists
+-------------------------
+
+- The provisioning scripts used during template build call `apt` and expect Debian-specific package names and file locations.
+- Debian/Ubuntu images use a filesystem layout and package tooling the scripts rely upon.
+
+Workarounds and contribution
+---------------------------
+
+There is no known workaround at the moment. If you need non-Debian support, please open an issue describing the use case or submit a PR that updates the provisioning scripts to support alternative package managers (e.g., `apk`, `yum`, `dnf`) and corresponding filesystem differences.
+
+Suggested PR wording
+--------------------
+
+Add a short note in the docs: "Custom template builds require Debian/Ubuntu-based base images (apt). Non-Debian images (Alpine, CentOS/RHEL, etc.) are not supported and will fail during the build process. Contributions to add non-Debian support are welcome; please open an issue or PR."