From 83bdb1a5155fb673beae055758dbba3e6409b115 Mon Sep 17 00:00:00 2001
From: Paul Rastoin <45004772+prastoin@users.noreply.github.com>
Date: Wed, 14 May 2025 15:17:06 +0200
Subject: [PATCH] [DOCS] New troubleshoot `password authentication failed for
 user "postgres"` (#12031)

# Introduction
Shorter and clearer issue
https://github.com/twentyhq/twenty/issues/11868
close https://github.com/twentyhq/twenty/issues/8701
---
 .../self-hosting/troubleshooting.mdx           | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx b/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx
index 82b5fdbb2..d9d04166e 100644
--- a/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx
+++ b/packages/twenty-website/src/content/developers/self-hosting/troubleshooting.mdx
@@ -11,6 +11,24 @@ here are some solutions for common problems.
 
 ### Self-hosting
 
+#### First install results in `password authentication failed for user "postgres"`
+
+🚨 **IMPORTANT: This solution is ONLY for fresh installations** 🚨
+If you have an existing Twenty instance with production data, **DO NOT** follow these steps as they will permanently delete your database!
+
+While installing Twenty for the first time, you might want to change the default database password.
+The password you set during the first installation becomes permanently stored in the database volume. If you later try to change this password in your configuration without removing the old volume, you'll get authentication errors because the database is still using the original password.
+
+⚠️ WARNING: Following steps will PERMANENTLY DELETE all database data! ⚠️
+Only proceed if this is a fresh installation with no important data.
+
+In order to update the `PG_DATABASE_PASSWORD` you need to:
+```sh
+# Update the PG_DATABASE_PASSWORD in .env
+docker compose down --volumes
+docker compose up -d
+```
+
 #### CR line breaks found [Windows]
 
 This is due to the line break characters of Windows and the git configuration. Try running: