diff --git a/docs/docs/20-usage/30-matrix-workflows.md b/docs/docs/20-usage/30-matrix-workflows.md
index 54dcafadd39..2ee152e43af 100644
--- a/docs/docs/20-usage/30-matrix-workflows.md
+++ b/docs/docs/20-usage/30-matrix-workflows.md
@@ -2,6 +2,11 @@
 
 Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.
 
+:::warning
+Woodpecker currently supports a maximum of **27 matrix axes** per workflow.
+If your matrix exceeds this number, any additional axes will be silently ignored.
+:::
+
 Example matrix definition:
 
 ```yaml
diff --git a/docs/versioned_docs/version-2.8/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-2.8/20-usage/30-matrix-workflows.md
index 95482052396..b56341bbba2 100644
--- a/docs/versioned_docs/version-2.8/20-usage/30-matrix-workflows.md
+++ b/docs/versioned_docs/version-2.8/20-usage/30-matrix-workflows.md
@@ -2,6 +2,11 @@
 
 Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.
 
+:::warning
+Woodpecker currently supports a maximum of **27 matrix axes** per workflow.
+If your matrix exceeds this number, any additional axes will be silently ignored.
+:::
+
 Example matrix definition:
 
 ```yaml
diff --git a/docs/versioned_docs/version-3.10/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-3.10/20-usage/30-matrix-workflows.md
index 54dcafadd39..2ee152e43af 100644
--- a/docs/versioned_docs/version-3.10/20-usage/30-matrix-workflows.md
+++ b/docs/versioned_docs/version-3.10/20-usage/30-matrix-workflows.md
@@ -2,6 +2,11 @@
 
 Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.
 
+:::warning
+Woodpecker currently supports a maximum of **27 matrix axes** per workflow.
+If your matrix exceeds this number, any additional axes will be silently ignored.
+:::
+
 Example matrix definition:
 
 ```yaml
diff --git a/docs/versioned_docs/version-3.11/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-3.11/20-usage/30-matrix-workflows.md
index 54dcafadd39..2ee152e43af 100644
--- a/docs/versioned_docs/version-3.11/20-usage/30-matrix-workflows.md
+++ b/docs/versioned_docs/version-3.11/20-usage/30-matrix-workflows.md
@@ -2,6 +2,11 @@
 
 Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.
 
+:::warning
+Woodpecker currently supports a maximum of **27 matrix axes** per workflow.
+If your matrix exceeds this number, any additional axes will be silently ignored.
+:::
+
 Example matrix definition:
 
 ```yaml
diff --git a/docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md b/docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md
index 54dcafadd39..2ee152e43af 100644
--- a/docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md
+++ b/docs/versioned_docs/version-3.9/20-usage/30-matrix-workflows.md
@@ -2,6 +2,11 @@
 
 Woodpecker has integrated support for matrix workflows. Woodpecker executes a separate workflow for each combination in the matrix, allowing you to build and test against multiple configurations.
 
+:::warning
+Woodpecker currently supports a maximum of **27 matrix axes** per workflow.
+If your matrix exceeds this number, any additional axes will be silently ignored.
+:::
+
 Example matrix definition:
 
 ```yaml