diff --git a/docs/modules/common/partials/InstallIntelliJ.adoc b/docs/modules/common/partials/InstallIntelliJ.adoc
index 74ac2e9864f..103ed6290f6 100644
--- a/docs/modules/common/partials/InstallIntelliJ.adoc
+++ b/docs/modules/common/partials/InstallIntelliJ.adoc
@@ -21,4 +21,6 @@ As soon as this is completed, press the `Restart IDE` button.
 
 The same can also be achieved by navigating to `File | Settings | Plugins` in case you already have an existing IntelliJ project running.
 
+include::common:partial$IntelliJUpdateEcjNote.adoc[]
+
 Congratulations! You have successfully set up IntelliJ IDEA for Scout development.
diff --git a/docs/modules/common/partials/IntelliJUpdateEcjNote.adoc b/docs/modules/common/partials/IntelliJUpdateEcjNote.adoc
new file mode 100644
index 00000000000..e288c44ea21
--- /dev/null
+++ b/docs/modules/common/partials/IntelliJUpdateEcjNote.adoc
@@ -0,0 +1,20 @@
+ifndef::finaldoc[]
+include::partial$_initDoc.adoc[]
+endif::finaldoc[]
+
+//-----------------------------------------------------------------------------
+//WARNING: this file is a text module, it should be embedded in a master asciidoctor document.
+//-----------------------------------------------------------------------------
+
+[NOTE]
+====
+IntelliJ currently ships with an outdated version of the Eclipse Compiler for Java (ECJ), which does *not* support Java 21 or later. Therefore, Scout {scout-version} requires *Eclipse Compiler 3.40.0*.
+
+To use ECJ 3.40.0 in IntelliJ:
+
+* https://repo1.maven.org/maven2/org/eclipse/jdt/ecj/3.40.0/ecj-3.40.0.jar[Download ECJ 3.40.0]
+* In IntelliJ, go to:
++
+`File | Settings | Build, Execution, Deployment | Compiler | Java Compiler`
+* Under *Eclipse Options*, set *Path to ECJ batch compiler tool* to the downloaded `ecj-3.40.0.jar` file.
+====
diff --git a/docs/modules/migration/partials/migration-guide-25.1.adoc b/docs/modules/migration/partials/migration-guide-25.1.adoc
index 4b6a0135128..d52ec7ef32e 100644
--- a/docs/modules/migration/partials/migration-guide-25.1.adoc
+++ b/docs/modules/migration/partials/migration-guide-25.1.adoc
@@ -92,6 +92,8 @@ Scout 25.1 requires at least the following:
 ** Node: >= 22.13.0
 ** Pnpm: >= 9.15.4
 
+include::common:partial$IntelliJUpdateEcjNote.adoc[]
+
 === Pnpm Settings Changes
 
 Pnpm 9 changed the default of `link-workspace-packages` from true to false, see