diff --git a/jOOQ/src/main/java/org/jooq/SelectOnStep.java b/jOOQ/src/main/java/org/jooq/SelectOnStep.java
index c653656e5f..f075416899 100644
--- a/jOOQ/src/main/java/org/jooq/SelectOnStep.java
+++ b/jOOQ/src/main/java/org/jooq/SelectOnStep.java
@@ -204,7 +204,10 @@ public interface SelectOnStep<R extends Record> {
      *
      * @see TableOnStep#onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @NotNull @CheckReturnValue
     @Support
@@ -218,7 +221,10 @@ public interface SelectOnStep<R extends Record> {
      *
      * @see TableOnStep#onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @NotNull @CheckReturnValue
     @Support
diff --git a/jOOQ/src/main/java/org/jooq/SelectQuery.java b/jOOQ/src/main/java/org/jooq/SelectQuery.java
index 0f64629e00..e06c19f82c 100644
--- a/jOOQ/src/main/java/org/jooq/SelectQuery.java
+++ b/jOOQ/src/main/java/org/jooq/SelectQuery.java
@@ -294,7 +294,10 @@ public interface SelectQuery<R extends Record> extends Select<R>, ConditionProvi
      * @param type The type of join
      * @see TableOnStep#onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @Support
     void addJoinOnKey(TableLike<?> table, JoinType type) throws DataAccessException;
@@ -307,7 +310,10 @@ public interface SelectQuery<R extends Record> extends Select<R>, ConditionProvi
      * @param keyFields The foreign key fields
      * @see TableOnStep#onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @Support
     void addJoinOnKey(TableLike<?> table, JoinType type, TableField<?, ?>... keyFields) throws DataAccessException;
diff --git a/jOOQ/src/main/java/org/jooq/TableOnStep.java b/jOOQ/src/main/java/org/jooq/TableOnStep.java
index a5d5955dab..a4377866f1 100644
--- a/jOOQ/src/main/java/org/jooq/TableOnStep.java
+++ b/jOOQ/src/main/java/org/jooq/TableOnStep.java
@@ -190,7 +190,10 @@ public interface TableOnStep<R extends Record> {
      *
      * @see #onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @NotNull
     @Support
@@ -204,7 +207,10 @@ public interface TableOnStep<R extends Record> {
      *
      * @see #onKey(ForeignKey)
      * @throws DataAccessException If there is no non-ambiguous key definition
-     *             known to jOOQ
+     *             known to jOOQ. <em>Please note that if you evolve your
+     *             schema, a previously non-ambiguous <code>ON KEY</code> clause
+     *             can suddenly become ambiguous on an existing query, so use
+     *             this clause with care.</em>
      */
     @NotNull
     @Support