diff --git a/docs/api.md b/docs/api.md
index 9ff6b3f4..98678851 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -5814,6 +5814,11 @@ int32
 <td>
 <p>HexWidth is the number of hex characters to use for the shard range start and end.
 If not set or set to 0, it will be automatically computed based on the number of requested shards.</p>
+<p>WARNING: DO NOT change the hex width in a partitioning after deploying.
+That&rsquo;s effectively deleting the old partitioning and adding a new one,
+which can lead to downtime or data loss. Instead, add an additional
+partitioning with the desired hex width, perform a resharding
+migration, and then remove the old partitioning.</p>
 </td>
 </tr>
 <tr>
diff --git a/docs/api/index.html b/docs/api/index.html
index 6cfb57d3..0fb435af 100644
--- a/docs/api/index.html
+++ b/docs/api/index.html
@@ -5816,6 +5816,11 @@ <h3 id="planetscale.com/v2.VitessKeyspaceEqualPartitioning">VitessKeyspaceEqualP
 <td>
 <p>HexWidth is the number of hex characters to use for the shard range start and end.
 If not set or set to 0, it will be automatically computed based on the number of requested shards.</p>
+<p>WARNING: DO NOT change the hex width in a partitioning after deploying.
+That&rsquo;s effectively deleting the old partitioning and adding a new one,
+which can lead to downtime or data loss. Instead, add an additional
+partitioning with the desired hex width, perform a resharding
+migration, and then remove the old partitioning.</p>
 </td>
 </tr>
 <tr>
diff --git a/pkg/apis/planetscale/v2/vitesskeyspace_types.go b/pkg/apis/planetscale/v2/vitesskeyspace_types.go
index 77bfcc8a..34d452a8 100644
--- a/pkg/apis/planetscale/v2/vitesskeyspace_types.go
+++ b/pkg/apis/planetscale/v2/vitesskeyspace_types.go
@@ -359,6 +359,13 @@ type VitessKeyspaceEqualPartitioning struct {
 
 	// HexWidth is the number of hex characters to use for the shard range start and end.
 	// If not set or set to 0, it will be automatically computed based on the number of requested shards.
+	//
+	// WARNING: DO NOT change the hex width in a partitioning after deploying.
+	//          That's effectively deleting the old partitioning and adding a new one,
+	//          which can lead to downtime or data loss. Instead, add an additional
+	//          partitioning with the desired hex width, perform a resharding
+	//          migration, and then remove the old partitioning.
+	//
 	// +kubebuilder:default=0
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=65536