diff --git a/docs/module-sources.rst b/docs/module-sources.rst
index 13401124..77c28ee9 100644
--- a/docs/module-sources.rst
+++ b/docs/module-sources.rst
@@ -487,6 +487,15 @@ property. Instead of a symlink this also often a script like:
 The ``subdir`` directory comes from the contents of the extracted snap
 and how that is installed.
 
+.. note::
+
+  Note that variables like ``$FLATPAK_DEST`` are not available in the
+  runtime sandbox or in the sandbox where ``apply_extra`` is executed
+  when installing the Flatpak.
+
+  Please avoid using them when creating the script in the manifest
+  as this will be incorrectly expanded.
+
 The commands needed to extract the snap are specified in the ``apply_extra``
 script. These can be any shell commands that run when installing the
 Flatpak package but note that it won't have access to anything outside
diff --git a/docs/sandbox-permissions.rst b/docs/sandbox-permissions.rst
index 1df319f1..c432ce7a 100644
--- a/docs/sandbox-permissions.rst
+++ b/docs/sandbox-permissions.rst
@@ -59,6 +59,12 @@ information on how to use them.
 Permissions guidelines
 ----------------------
 
+.. note::
+
+  Note, that these permissions are completely static and variable
+  expansion or substitution (for example in ``--filesystem`` or ``--env``)
+  is not possible.
+
 While application developers have control over the sandbox permissions they
 wish to configure, good practice is encouraged and can be enforced. For
 example, the Flathub hosting service places requirements on which permissions