diff --git a/reference/mysqlnd_ms/ini.xml b/reference/mysqlnd_ms/ini.xml
index 4e844ce0b4..88ec785d89 100755
--- a/reference/mysqlnd_ms/ini.xml
+++ b/reference/mysqlnd_ms/ini.xml
@@ -97,7 +97,19 @@
      </para>
      <para>
       This setting is not only useful to restrict PHP to certain servers but also
-      to debug configuration file problems.
+      to debug configuration file problems. The configuration file validity is checked
+      at two different stages. The first check is performed when PHP begins to
+      handle a web request. At this point the plugin reads and decodes the configuration
+      file. Errors thrown at this early stage in an extensions life cycle may not be
+      shown properly to the user. Thus, the plugin buffers the errors, if any, and
+      additionally displays them when establishing a connection to MySQL.
+      By default a buffered startup error will emit an error of type
+      <literal>E_WARNING</literal>.  If <literal>force_config_usage</literal> is set,
+      the error type used is <literal>E_RECOVERABLE_ERROR</literal>.
+     </para>
+     <para>
+      Please, see also <link linkend="mysqlnd-ms.plugin-ini-json.debug_config">configuration
+      file debugging notes</link>.
      </para>
     </listitem>
    </varlistentry>
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml
index 7699df8335..00da3b8a44 100755
--- a/reference/mysqlnd_ms/quickstart.xml
+++ b/reference/mysqlnd_ms/quickstart.xml
@@ -201,7 +201,8 @@ mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
    errors may appear in some log files only. Further validation is done when a connection
    is to be established and the configuration file is searched for valid sections.
    Setting <link linkend="ini.mysqlnd-ms.force-config-usage">mysqlnd_ms.force_config_usage</link>
-   may help debugging a faulty setup.
+   may help debugging a faulty setup. Please, see also
+   <link linkend="mysqlnd-ms.plugin-ini-json.debug_config">configuration file debugging notes</link>.
   </para>
 
  </section>
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index cfd5ea1444..01105c407d 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/reference/mysqlnd_ms/setup.xml
@@ -382,6 +382,93 @@ $mysqli = new mysqli("localhost", "username", "password", "database");
     </programlisting>
    </example>
   </para>
+  <para xml:id="mysqlnd-ms.plugin-ini-json.debug_config">
+   The validity of the configuration file is checked both when reading the
+   configuration file and later when establishing a connection. The configuration
+   file is read during PHP request startup. At this early stage a PHP extension
+   may not display error messages properly. In the worst case, no error
+   is shown and a connection attempt fails without an adequate error message.
+   This problem has been cured in version 1.5.0.
+  </para>
+  <para>
+   <example>
+    <title>Common error message in case of configuration file issues (upto version 1.5.0)</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("myapp", "username", "password", "database");
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code
+
+Warning: mysqli::mysqli(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Name or service not known in Command line code on line 1
+
+Warning: mysqli::query(): Couldn't fetch mysqli in Command line code on line 1
+
+Fatal error: Call to a member function fetch_assoc() on a non-object in Command line code on line 1
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   Since version 1.5.0 startup errors are additionally buffered and emitted when
+   a connection attempt is made. Use the configuration directive
+   <link linkend="ini.mysqlnd-ms.force-config-usage"><literal>mysqlnd_ms.force_config_usage</literal></link>
+   to set the error type used to display buffered errors. By default an error
+   of type <literal>E_WARNING</literal> will be emitted.
+ </para>
+ <para>
+   <example>
+    <title>Improved configuration file validation since 1.5.0</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("myapp", "username", "password", "database");
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code on line 1
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   It can be useful to set <link linkend="ini.mysqlnd-ms.force-config-usage"><literal>mysqlnd_ms.force_config_usage = 1</literal></link>
+   when debugging potential configuration file errors. This will not only turn the
+   type of buffered startup errors into <literal>E_RECOVERABLE_ERROR</literal> but also
+   help detecting misspelled section names.
+  </para>
+  <para>
+   <example>
+    <title>Possibly more precise error due to <literal>mysqlnd_ms.force_config_usage=1</literal></title>
+    <programlisting role="ini">
+<![CDATA[
+mysqlnd_ms.force_config_usage=1
+]]>
+    </programlisting>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("invalid_section", "username", "password", "database");
+?>
+]]>
+    </programlisting>
+&example.outputs;
+    <screen>
+<![CDATA[
+Warning: mysqli::mysqli(): (mysqlnd_ms) Exclusive usage of configuration enforced but did not find the correct INI file section (invalid_section) in Command line code on line 1 line 1
+]]>
+    </screen>
+
+   </example>
+  </para>
   <para>
    Here is a short explanation of the configuration directives that can be used.
   </para>