diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md
index 0d973013..261c2a39 100644
--- a/docs/src/main/paradox/index.md
+++ b/docs/src/main/paradox/index.md
@@ -20,6 +20,7 @@ The Akka Persistence R2DBC plugin allows for using SQL database with R2DBC as a
 * [Migration tool](migration.md)
 * [Migration Guide](migration-guide.md)
 * [Native Image](native-image.md)
+* [Troubleshooting](troubleshooting.md)
 * [Contributing](contributing.md)
 
 @@@
diff --git a/docs/src/main/paradox/troubleshooting.md b/docs/src/main/paradox/troubleshooting.md
new file mode 100644
index 00000000..c40c2165
--- /dev/null
+++ b/docs/src/main/paradox/troubleshooting.md
@@ -0,0 +1,17 @@
+# Troubleshooting 
+
+## Failing to use the configured plugin 
+
+If you see something like this, where the driver is not available:
+
+```
+ Unable to create a ConnectionFactory for 'ConnectionFactoryOptions{options={...}}'. Available drivers: [ pool ]
+```
+
+It is likely because you are building a shaded jar with all dependencies and the ´META-INF/services` entry for 
+the R2DBC driver for the database you are using got lost.
+
+If using maven shading plugin, make sure to use the [ServicesResourceTransformer](https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#ServicesResourceTransformer). 
+
+For other build tools, make sure the tool merges `META-INF/services/io.r2dbc.spi.ConnectionFactoryProvider` 
+files rather than dropping one when there is a conflict.
\ No newline at end of file