diff --git a/docs/docs/20-usage/30-matrix-workflows.md b/docs/docs/20-usage/30-matrix-workflows.md
index 54dcafadd..2ee152e43 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 954820523..b56341bbb 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 54dcafadd..2ee152e43 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 54dcafadd..2ee152e43 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 54dcafadd..2ee152e43 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