From 88b7afb195d207d110df751db7bb6496ec613e58 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 01:51:50 +0000
Subject: [PATCH] feat: log BACKEND_URL at frontend startup and include target
 URL in proxy errors

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
Agent-Logs-Url: https://github.com/christianlouis/pop_puller_to_gmail/sessions/131238a2-437c-4a85-b98b-fcb3d80e69e0
---
 CHANGELOG.md                               | 1 +
 docs/TODO.md                               | 1 +
 frontend/src/app/api/v1/[...path]/route.ts | 2 +-
 frontend/src/instrumentation.ts            | 4 ++++
 4 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/instrumentation.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cdf54b3..167826d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Upgraded `sqlalchemy` from `2.0.25` to `2.0.48` to fix `AssertionError: Class ... directly inherits TypingOnly but has additional attributes` on Python 3.14 (`__static_attributes__`, `__firstlineno__`)
 
 ### Added
+- **Backend URL logged at startup**: The Next.js server now logs the resolved `BACKEND_URL` (e.g. `[proxy] BACKEND_URL = http://backend:8000`) via `src/instrumentation.ts` when the server starts, making it easy to diagnose `ECONNREFUSED` proxy errors. The per-request error log now also includes the full target URL.
 - **Dual-registry Docker deployment**: CI now builds separate backend and frontend images and pushes to both GHCR (`ghcr.io`) and private registry (`registry.cklnet.com`) using a matrix strategy
 - **Database-backed configuration**: `AppSetting` model and `ConfigService` for hybrid config (DB-first, env-var fallback)
 - Admin API endpoints for managing settings (`GET/PUT/DELETE /api/v1/settings`)
diff --git a/docs/TODO.md b/docs/TODO.md
index 4f26870..bd6decb 100644
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -99,6 +99,7 @@ Comprehensive task breakdown for repository improvements and production readines
 - [x] Upgrade SQLAlchemy to 2.0.48 to fix Python 3.14 test failures
 - [x] Fix Docker build failure: wrap `useSearchParams()` in Suspense boundary in `/auth/callback` page
 - [x] Fix frontend API URL hardcoded to `localhost:8000` in production: replaced build-time `NEXT_PUBLIC_API_URL` with a runtime Next.js Route Handler proxy (`/api/v1/[...path]`) reading `BACKEND_URL` at server startup
+- [x] Log `BACKEND_URL` at frontend server startup and include target URL in per-request proxy error messages
 
 ### In Progress 🔨
 - [ ] Configure branch protection rules
diff --git a/frontend/src/app/api/v1/[...path]/route.ts b/frontend/src/app/api/v1/[...path]/route.ts
index 41c7dae..160efbf 100644
--- a/frontend/src/app/api/v1/[...path]/route.ts
+++ b/frontend/src/app/api/v1/[...path]/route.ts
@@ -29,7 +29,7 @@ async function handler(request: NextRequest, context: RouteContext) {
       headers: upstream.headers,
     });
   } catch (error) {
-    console.error("Proxy error forwarding to backend:", error);
+    console.error(`Proxy error forwarding to backend (target: ${targetUrl}):`, error);
     return NextResponse.json({ detail: "Backend unavailable" }, { status: 502 });
   }
 }
diff --git a/frontend/src/instrumentation.ts b/frontend/src/instrumentation.ts
new file mode 100644
index 0000000..5c5ed08
--- /dev/null
+++ b/frontend/src/instrumentation.ts
@@ -0,0 +1,4 @@
+export async function register() {
+  const backendUrl = process.env.BACKEND_URL ?? "http://localhost:8000";
+  console.log(`[proxy] BACKEND_URL = ${backendUrl}`);
+}