diff --git a/content/reference/compose-file/configs.md b/content/reference/compose-file/configs.md
index 860f16895e9..ada26d0309e 100644
--- a/content/reference/compose-file/configs.md
+++ b/content/reference/compose-file/configs.md
@@ -87,4 +87,11 @@ configs:
     environment: "SIMPLE_CONFIG_VALUE"
 ```
 
+> [!IMPORTANT]
+>
+> The `environment` and `content` sources aren't supported by
+> `docker stack deploy`: the command fails to read the config. Use the
+> `file` source, or an [`external`](/manuals/engine/swarm/configs.md)
+> config created with `docker config create`.
+
 If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.
diff --git a/content/reference/compose-file/secrets.md b/content/reference/compose-file/secrets.md
index 136ccab20dd..3b87ad8f837 100644
--- a/content/reference/compose-file/secrets.md
+++ b/content/reference/compose-file/secrets.md
@@ -39,6 +39,13 @@ secrets:
     environment: "OAUTH_TOKEN"
 ```
 
+> [!IMPORTANT]
+>
+> The `environment` source isn't supported by `docker stack deploy`:
+> the command fails to read the secret. Use the `file` source, or an
+> [`external`](/manuals/engine/swarm/secrets.md) secret created with
+> `docker secret create`.
+
 ## Additional resources
 
 For more information, see [How to use secrets in Compose](/manuals/compose/how-tos/use-secrets.md).