diff --git a/documentation/src/main/asciidoc/reference/introduction.adoc b/documentation/src/main/asciidoc/reference/introduction.adoc
index c72c13522..0a82767c3 100644
--- a/documentation/src/main/asciidoc/reference/introduction.adoc
+++ b/documentation/src/main/asciidoc/reference/introduction.adoc
@@ -1053,10 +1053,25 @@ Hibernate Reactive session associated with the context.
 === Vert.x instance service
 
 The `VertxInstance` service defines how Hibernate Reactive obtains an instance
-of Vert.x. The default implementation just creates one the first time it's
-needed. But if your program requires control over how the Vert.x instance is
-created, or how it's obtained, you can override the default implementation and
-provide your own `VertxInstance`. Let's consider this example:
+of Vert.x when there is no instance associated with the calling thread. The
+default implementation just creates one the first time it's needed. But if your
+program requires control over how the Vert.x instance is created, or how it's
+obtained, you can override the default implementation and provide your own
+`VertxInstance`.
+
+IMPORTANT: If your program starts Vert.x externally to Hibernate Reactive, and
+you don't tell Hibernate Reactive how to obtain this instance of Vert.x by
+specifying an implementation of `VertxInstance`, you might end up with multiple
+instances of `Vertx` in your program, resulting in confusing error messages.
+
+There are two ways to solve this problem:
+
+- make sure Hibernate Reactive is never called from a thread  with no current
+  Vert.x context, by using `runOnContext()` in a disciplined way, as described
+  in the previous section, or
+- provide your own implementation of `VertxInstance`.
+
+Let's consider this example:
 
 [source, JAVA, indent=0]
 ----
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/VertxInstance.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/VertxInstance.java
index 0b355e697..4062c7176 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/VertxInstance.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/VertxInstance.java
@@ -7,19 +7,27 @@
 
 import io.vertx.core.Vertx;
 
-import org.hibernate.reactive.pool.impl.DefaultSqlClientPool;
 import org.hibernate.service.Service;
 
 /**
- * Used by {@link DefaultSqlClientPool} and
- * {@link org.hibernate.reactive.context.impl.VertxContext}
- * to obtain an instance of {@link Vertx}. The default instance is
- * {@link org.hibernate.reactive.vertx.impl.DefaultVertxInstance}.
+ * Used by {@link org.hibernate.reactive.pool.impl.DefaultSqlClientPool}
+ * and {@link org.hibernate.reactive.context.impl.VertxContext} to
+ * obtain an instance of {@link Vertx}.
  * <p>
- * A program may integrate a custom {@link VertxInstance}
- * with Hibernate Reactive by contributing a new service using a
- * {@link org.hibernate.boot.registry.StandardServiceInitiator}
- * or from code-based Hibernate configuration by calling
+ * The default implementation is
+ * {@link org.hibernate.reactive.vertx.impl.DefaultVertxInstance},
+ * which creates a new instance of {@code Vertx} if there is no
+ * instance already associated with the calling thread. This default
+ * behavior may cause problems in programs which have an instance of
+ * {@code Vertx} whose lifecycle is managed externally to Hibernate
+ * Reactive, and in such cases
+ * {@link org.hibernate.reactive.vertx.impl.ProvidedVertxInstance}
+ * or a custom-written {@code VertxInstance} should be used.
+ * <p>
+ * A program may integrate a custom {@link VertxInstance} with
+ * Hibernate Reactive by contributing a new service using a
+ * {@link org.hibernate.boot.registry.StandardServiceInitiator} or
+ * from code-based Hibernate configuration by calling the method
  * {@link org.hibernate.reactive.provider.ReactiveServiceRegistryBuilder#addService}.
  *
  * <pre>{@code
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/DefaultVertxInstance.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/DefaultVertxInstance.java
index 8bf81fb9e..04e0f6136 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/DefaultVertxInstance.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/DefaultVertxInstance.java
@@ -20,9 +20,15 @@
  * A singleton instance of {@link Vertx} that is created on
  * demand and destroyed automatically along with the Hibernate
  * {@link org.hibernate.SessionFactory#close() session factory}.
+ * <p>
+ * Programs which require Hibernate reactive to use an instance
+ * of {@code Vertx} whose lifecycle is managed externally to
+ * Hibernate Reactive should use {@link ProvidedVertxInstance}
+ * instead.
  *
  * @author Sanne Grinovero <sanne@hibernate.org>
- * @see ProvidedVertxInstance if you need to a different instance
+ *
+ * @see ProvidedVertxInstance
  */
 public final class DefaultVertxInstance implements VertxInstance, Stoppable, Startable {
 
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/ProvidedVertxInstance.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/ProvidedVertxInstance.java
index d697e49e8..1249a7d38 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/ProvidedVertxInstance.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/impl/ProvidedVertxInstance.java
@@ -13,7 +13,7 @@
 
 /**
  * An implementation of {@link VertxInstance} which allows the client
- * to provide an instance of {@link Vertx} whose lifecyle is managed
+ * to provide an instance of {@link Vertx} whose lifecycle is managed
  * externally to Hibernate Reactive. The {@code ProvidedVertxInstance}
  * must be registered explicitly with Hibernate by calling
  * {@link org.hibernate.reactive.provider.ReactiveServiceRegistryBuilder#addService}.
diff --git a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/package-info.java b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/package-info.java
index c3db86964..c8638af32 100644
--- a/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/package-info.java
+++ b/hibernate-reactive-core/src/main/java/org/hibernate/reactive/vertx/package-info.java
@@ -1,5 +1,7 @@
 /**
- * Integration with Vert.x.
+ * Integration with Vert.x. Allows a program to customize how
+ * instances of {@link io.vertx.core.Vertx} should be obtained
+ * by Hibernate Reactive.
  *
  * @see org.hibernate.reactive.vertx.VertxInstance
  */