From ac32b630979386f9832bbe807ed7f82ab493a0c4 Mon Sep 17 00:00:00 2001
From: miguel <miguelg71921@gmail.com>
Date: Sat, 20 Sep 2025 16:27:12 -0700
Subject: [PATCH] Improve failed act logs

---
 .changeset/tasty-candles-retire.md |  5 +++++
 lib/handlers/actHandler.ts         | 10 ++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/tasty-candles-retire.md

diff --git a/.changeset/tasty-candles-retire.md b/.changeset/tasty-candles-retire.md
new file mode 100644
index 000000000..7ad91e8ec
--- /dev/null
+++ b/.changeset/tasty-candles-retire.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Improve failed act error logs
diff --git a/lib/handlers/actHandler.ts b/lib/handlers/actHandler.ts
index 91893b243..47144ce7d 100644
--- a/lib/handlers/actHandler.ts
+++ b/lib/handlers/actHandler.ts
@@ -163,7 +163,7 @@ export class StagehandActHandler {
         if (observeResults.length === 0) {
           return {
             success: false,
-            message: `Failed to self heal act: No observe results found for action`,
+            message: `Failed to self heal act: Element not found.`,
             action: actCommand,
           };
         }
@@ -264,9 +264,15 @@ export class StagehandActHandler {
       });
 
       if (observeResults.length === 0) {
+        this.logger({
+          category: "action",
+          message:
+            "No elements found to act on. Check best practices for act: https://docs.stagehand.com/basics/act",
+          level: 2,
+        });
         return {
           success: false,
-          message: `Failed to perform act: No observe results found for action`,
+          message: `Failed to perform act: No elements found to act on.`,
           action,
         };
       }