diff --git a/docs/v3/contributing/self-hosting.mdx b/docs/v3/contributing/self-hosting.mdx
index b062a766..f78d2217 100644
--- a/docs/v3/contributing/self-hosting.mdx
+++ b/docs/v3/contributing/self-hosting.mdx
@@ -178,6 +178,12 @@ CREATE EXTENSION IF NOT EXISTS vector;
 \q
 ```
 
+<Note>
+**Least-privilege database roles.** Honcho runs `CREATE EXTENSION IF NOT EXISTS vector` before migrations and again at startup, so if the role in `DB_CONNECTION_URI` can't create extensions, both fail with a privilege error — `IF NOT EXISTS` doesn't help, because Postgres checks the privilege first.
+
+Run the statement above once as a superuser (or `rds_superuser`) and the application role needs no extension privileges. See [Troubleshooting](/v3/contributing/troubleshooting) if you hit this.
+</Note>
+
 ### 4. Configure Environment
 
 Create a `.env` file with your settings:
diff --git a/docs/v3/contributing/troubleshooting.mdx b/docs/v3/contributing/troubleshooting.mdx
index d9b745a1..29748e2f 100644
--- a/docs/v3/contributing/troubleshooting.mdx
+++ b/docs/v3/contributing/troubleshooting.mdx
@@ -204,6 +204,20 @@ uv run alembic history
 uv run alembic upgrade head
 ```
 
+### "permission denied to create extension \"vector\""
+
+**Cause:** The role in `DB_CONNECTION_URI` is not a superuser and lacks privileges to create extensions. Honcho issues `CREATE EXTENSION IF NOT EXISTS vector` both before running migrations and again at server startup, so this fails in both places. `IF NOT EXISTS` does not help — Postgres checks the privilege before checking whether the extension exists.
+
+**Fix:** Preinstall pgvector once with a privileged role (superuser, or `rds_superuser` on RDS) in the Honcho database:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+The `IF NOT EXISTS` calls then short-circuit and the application role needs no extension privileges. This is the supported path for deployments where the platform, not the application, owns extension management.
+
+You won't hit this with `docker compose` — the bundled database service runs `database/init.sql` as an initdb script, which creates the extension before Honcho ever connects. It comes up on managed Postgres, Kubernetes operators, and other setups where you bring your own database and its role is deliberately not a superuser.
+
 ## Cache & Redis
 
 ### Redis is optional