From 4442120c41459d9a1bdc62d11b612b2a968a8d3c Mon Sep 17 00:00:00 2001 From: gimenes Date: Wed, 8 Apr 2026 17:14:44 -0300 Subject: [PATCH 1/2] fix(services): improve error message for missing locale on Linux When embedded-postgres fails to initialize on Linux systems without en_US.UTF-8 locale, the error message is cryptic. Add a clear hint pointing users to install the missing locale. Co-Authored-By: Claude Opus 4.6 (1M context) --- apps/mesh/src/services/ensure-services.ts | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/apps/mesh/src/services/ensure-services.ts b/apps/mesh/src/services/ensure-services.ts index 2089ca68d2..b46c08ca88 100644 --- a/apps/mesh/src/services/ensure-services.ts +++ b/apps/mesh/src/services/ensure-services.ts @@ -334,6 +334,25 @@ async function ensurePostgres(home: string): Promise { try { await pg.initialise(); } catch (initErr) { + const errMsg = + initErr instanceof Error ? initErr.message : String(initErr); + + // Detect missing locale — embedded-postgres requires en_US.UTF-8 which + // is not available on minimal Linux installations (e.g. Ubuntu minimal, + // Alpine, slim Docker images). + if ( + errMsg.includes("init script exited with code 1") || + errMsg.includes("invalid locale") + ) { + console.error( + `[ensurePostgres] PostgreSQL initialisation failed. This is likely caused by a missing locale.\n` + + ` embedded-postgres requires the "en_US.UTF-8" locale, which may not be installed on all Linux distros.\n` + + ` To fix, run:\n` + + ` sudo apt-get install -y locales && sudo locale-gen en_US.UTF-8\n` + + ` Then retry.`, + ); + } + // initdb may have been killed by a signal (exit code null) due to a race // with another process initializing the same data directory. Log the // error for debugging — do NOT remove the data dir as it may contain From 266eac262eb433bee51b9e6115822211bc377c34 Mon Sep 17 00:00:00 2001 From: gimenes Date: Wed, 8 Apr 2026 17:15:22 -0300 Subject: [PATCH 2/2] fix(services): use "Linux systems" wording in locale error message Co-Authored-By: Claude Opus 4.6 (1M context) --- apps/mesh/src/services/ensure-services.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/mesh/src/services/ensure-services.ts b/apps/mesh/src/services/ensure-services.ts index b46c08ca88..9634ba0383 100644 --- a/apps/mesh/src/services/ensure-services.ts +++ b/apps/mesh/src/services/ensure-services.ts @@ -346,7 +346,7 @@ async function ensurePostgres(home: string): Promise { ) { console.error( `[ensurePostgres] PostgreSQL initialisation failed. This is likely caused by a missing locale.\n` + - ` embedded-postgres requires the "en_US.UTF-8" locale, which may not be installed on all Linux distros.\n` + + ` embedded-postgres requires the "en_US.UTF-8" locale, which may not be installed on all Linux systems.\n` + ` To fix, run:\n` + ` sudo apt-get install -y locales && sudo locale-gen en_US.UTF-8\n` + ` Then retry.`,