diff --git a/www/apps/docs/content/create-medusa-app.mdx b/www/apps/docs/content/create-medusa-app.mdx
index 57f0668dec..9745e27dcf 100644
--- a/www/apps/docs/content/create-medusa-app.mdx
+++ b/www/apps/docs/content/create-medusa-app.mdx
@@ -17,6 +17,7 @@ import FreshInstallationSection from './troubleshooting/awilix-resolution-error/
 import EaddrinuseSection from './troubleshooting/eaddrinuse.md'
 import InvalidTokenError from './troubleshooting/create-medusa-app-errors/_no-browser-token-error.md'
 import PostgresDockerError from './troubleshooting/database-errors/_docker.md'
+import DbUrlError from './troubleshooting/create-medusa-app-errors/_db-url-error.md'
 
 # Install Medusa with create-medusa-app
 
@@ -217,6 +218,10 @@ Based on what you're building, you can find a development path for you in the Re
 
 <DetailsList
   sections={[
+    {
+      title: 'Can\'t connect to database with --db-url option',
+      content: <DbUrlError />
+    },
     {
       title: 'Error: EADDRINUSE',
       content: <EaddrinuseSection />
diff --git a/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx b/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx
index 8260021468..03bd4e11d8 100644
--- a/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx
+++ b/www/apps/docs/content/troubleshooting/create-medusa-app-errors.mdx
@@ -6,6 +6,7 @@ import TypeError from './create-medusa-app-errors/_typeerror.md'
 import OtherErrors from './create-medusa-app-errors/_other-errors.mdx'
 import InvalidTokenError from './create-medusa-app-errors/_no-browser-token-error.md'
 import DockerSection from "./database-errors/_docker.md"
+import DbUrlError from './create-medusa-app-errors/_db-url-error.md'
 
 ## TypeError: cmd is not a function
 
@@ -25,6 +26,12 @@ import DockerSection from "./database-errors/_docker.md"
 
 ---
 
+## Can't connect to database with --db-url option
+
+<DbUrlError />
+
+---
+
 ## Other Errors
 
 <OtherErrors />
\ No newline at end of file
diff --git a/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_db-url-error.md b/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_db-url-error.md
new file mode 100644
index 0000000000..4703f82d23
--- /dev/null
+++ b/www/apps/docs/content/troubleshooting/create-medusa-app-errors/_db-url-error.md
@@ -0,0 +1,9 @@
+If you use the `--db-url` option with the `create-medusa-app` command and the connection to the database fails, try the following:
+
+- Specifying `?sslmode=require` at the end of the connection URL. Some PostgreSQL hosting providers, like Vercel, require passing this option. For example:
+
+```bash
+npx create-medusa-app@latest --db-url "postgres://default:<password><host-region>.postgres.vercel-storage.com:5432/verceldb?sslmode=require"
+```
+
+- Changing the password to remove special characters. PostgreSQL requires encoding passwords if they have special characters. While the `create-medusa-app` command handles this automatically when you specify the password to the `create-medusa-app` command, when you pass a connection URL with the `--db-url` the command uses that URL as-is. So, you must either encode the special characters in the password yourself, or remove the special characters in the password.