From b680faa4dca8dacf2b3ff7968b789dd62a6f68da Mon Sep 17 00:00:00 2001
From: Shobhit Sahani <109831134+shobhitsahani@users.noreply.github.com>
Date: Thu, 26 Mar 2026 01:17:29 +0000
Subject: [PATCH] fix(shared): improve config validation error message for
 local git connections

When a file:// URL is detected in a failing connection, append a hint
to the error message explaining that the repository must be mounted
into the Docker container and the URL must reflect the container-internal
path, not the host machine path.

Fixes #1044
---
 packages/shared/src/env.server.ts | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/shared/src/env.server.ts b/packages/shared/src/env.server.ts
index 95006d875..eb0d598f6 100644
--- a/packages/shared/src/env.server.ts
+++ b/packages/shared/src/env.server.ts
@@ -107,7 +107,18 @@ export const loadConfig = async (configPath?: string): Promise<SourcebotConfig>
     const config = JSON.parse(stripJsonComments(configContent)) as SourcebotConfig;
     const isValidConfig = ajv.validate(indexSchema, config);
     if (!isValidConfig) {
-        throw new Error(`Config file '${configPath}' is invalid: ${ajv.errorsText(ajv.errors)}`);
+        const fileUrlConnections = Object.entries((config as any)?.connections ?? {})
+            .filter(([, conn]: [string, any]) => conn?.url?.startsWith('file://'))
+            .map(([name]) => name);
+
+        const hint = fileUrlConnections.length > 0
+            ? ` Hint: connection(s) [${fileUrlConnections.join(', ')}] use a file:// URL. ` +
+              `Make sure the local repository is mounted into the Docker container and ` +
+              `the URL reflects the container-internal path (e.g. file:///repos/my-repo), ` +
+              `not the host machine path.`
+            : '';
+
+        throw new Error(`Config file '${configPath}' is invalid: ${ajv.errorsText(ajv.errors)}.${hint}`);
     }
     return config;
 }