diff --git a/configuration.rst b/configuration.rst
index 88e96cb92e5..661b2a972e0 100644
--- a/configuration.rst
+++ b/configuration.rst
@@ -227,7 +227,7 @@ This is referenced inside ``config/packages/doctrine.yaml``:
         dbal:
             url: '%env(DATABASE_URL)%'
 
-            # the resolve: prefix will resolve parameters *inside* the env variable
+            # The `resolve:` prefix replaces container params by their values inside the env variable:
             # url: '%env(resolve:DATABASE_URL)%'
 
 For more details about environment variables, see :ref:`config-env-vars`.
diff --git a/doctrine.rst b/doctrine.rst
index 8506ddaf86b..493be738bf6 100644
--- a/doctrine.rst
+++ b/doctrine.rst
@@ -49,10 +49,12 @@ The database connection information is stored as an environment variable called
 
 .. caution::
 
-    If the username, password or database name contain any character considered
-    special in a URI (such as ``!``, ``@``, ``$``, ``#``), you must encode them.
+    If the username, password, host or database name contain any character considered
+    special in a URI (such as ``!``, ``@``, ``$``, ``#``, ``/``), you must encode them.
     See `RFC 3986`_ for the full list of reserved characters or use the
-    :phpfunction:`urlencode` function to encode them.
+    :phpfunction:`urlencode` function to encode them. In this case you need to remove
+    the ``resolve:`` prefix in ``config/packages/doctrine.yaml`` to avoid errors:
+    ``url: '%env(resolve:DATABASE_URL)%'``
 
 Now that your connection parameters are setup, Doctrine can create the ``db_name``
 database for you: