diff --git a/libbeat/docs/shared-docker.asciidoc b/libbeat/docs/shared-docker.asciidoc
index da5088072b0..1c62313bed0 100644
--- a/libbeat/docs/shared-docker.asciidoc
+++ b/libbeat/docs/shared-docker.asciidoc
@@ -63,6 +63,8 @@ The following checks were performed on each of these signatures:
 
 ==== Run the {beatname_uc} setup
 
+IMPORTANT: A link:https://github.com/elastic/beats/issues/42038[known issue] in version 8.17.0 prevents {beats} Docker images from starting when no options are provided. When running an image on that version, add an `--environment container` parameter to avoid the problem. This is planned to be addressed in issue link:https://github.com/elastic/beats/pull/42060[#42060].
+
 Running {beatname_uc} with the setup command will create the index pattern and
 load visualizations
 ifndef::no_dashboards[]