From 6f37fe0acc12372d50785106740e83ffc4508f6d Mon Sep 17 00:00:00 2001
From: Kastrah <abdulkhaliqakinwunmi@gmail.com>
Date: Mon, 26 Jan 2026 11:05:59 +0100
Subject: [PATCH] fix: detect and sanitize HTML error pages in agent responses

---
 CHANGELOG.md                             | 1 +
 src/agents/pi-embedded-helpers/errors.ts | 6 ++++++
 2 files changed, 7 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c274f668a..c7cf463c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - Web UI: hide internal `message_id` hints in chat bubbles.
 - Heartbeat: normalize target identifiers for consistent routing.
+- Agent errors: detect and sanitize HTML error pages from external APIs (prevents Next.js 404 pages being sent to messaging channels).
 
 ## 2026.1.23-1
 
diff --git a/src/agents/pi-embedded-helpers/errors.ts b/src/agents/pi-embedded-helpers/errors.ts
index e8fb7a4d1..1441877e4 100644
--- a/src/agents/pi-embedded-helpers/errors.ts
+++ b/src/agents/pi-embedded-helpers/errors.ts
@@ -273,6 +273,12 @@ export function formatAssistantErrorText(
     return formatRawAssistantErrorForUi(raw);
   }
 
+  // Detect HTML error pages (e.g., Next.js 404s from misconfigured API endpoints)
+  if (raw.includes("<!DOCTYPE") || raw.includes("<html") || /<head[\s>]/.test(raw)) {
+    console.warn("[formatAssistantErrorText] HTML error page received:", raw.slice(0, 200));
+    return "The AI service returned an unexpected error page. The API endpoint may be misconfigured or temporarily unavailable.";
+  }
+
   // Never return raw unhandled errors - log for debugging but return safe message
   if (raw.length > 600) {
     console.warn("[formatAssistantErrorText] Long error truncated:", raw.slice(0, 200));