From 08a82c11894262867fc0e84ea61a461b8d1dd9ea Mon Sep 17 00:00:00 2001
From: Cristian Dominguez <cdominguez@salesforce.com>
Date: Thu, 26 Mar 2026 21:48:03 -0300
Subject: [PATCH] fix: better error msg for `Org.getFrontDoorUrl`

---
 messages/org.md                         |  8 ++++++++
 schemas/project-scratch-def.schema.json |  1 +
 src/org/org.ts                          | 14 +++++++++++---
 3 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/messages/org.md b/messages/org.md
index 7839df2367..4e7a1d0a70 100644
--- a/messages/org.md
+++ b/messages/org.md
@@ -74,6 +74,14 @@ The sandbox %s cannot resume with status of %s.
 
 Failed to generate a frontdoor URL.
 
+# FrontdoorURLBadOauthToken
+
+Failed to generate a frontdoor URL.
+
+# FrontdoorURLBadOauthToken.actions
+
+- Check that the user "%s" does not have the "API Only User" permission assigned, it prevents browser access.
+
 # FlowIdNotFound
 
 ID not found for Flow %s.
diff --git a/schemas/project-scratch-def.schema.json b/schemas/project-scratch-def.schema.json
index 89c4b6f071..9bed7c01ac 100644
--- a/schemas/project-scratch-def.schema.json
+++ b/schemas/project-scratch-def.schema.json
@@ -452,6 +452,7 @@
               "EinsteinGPTForDevelopers",
               "EinsteinRecommendationBuilder",
               "EinsteinRecommendationBuilderMetadata",
+              "EinsteinSalesRepFdbk",
               "EinsteinSearch",
               "EinsteinVisits",
               "EinsteinVisitsED",
diff --git a/src/org/org.ts b/src/org/org.ts
index ecd03f1ab2..6f3fd33dd8 100644
--- a/src/org/org.ts
+++ b/src/org/org.ts
@@ -392,9 +392,17 @@ export class Org extends AsyncOptionalCreatable<Org.Options> {
       singleAccessUrl.searchParams.append('redirect_uri', redirectUri);
     }
 
-    const response = await this.connection.requestGet<SingleAccessUrlRes>(singleAccessUrl.toString());
-    if (response.frontdoor_uri) return response.frontdoor_uri;
-    throw new SfError(messages.getMessage('FrontdoorURLError')).setData(response);
+    try {
+      const response = await this.connection.requestGet<SingleAccessUrlRes>(singleAccessUrl.toString());
+      if (response.frontdoor_uri) return response.frontdoor_uri;
+      throw new SfError(messages.getMessage('FrontdoorURLError')).setData(response);
+    } catch (err) {
+      // See: https://help.salesforce.com/s/articleView?id=xcloud.frontdoor_singleaccess.htm&type=5
+      if (err instanceof Error && err.message.includes('Bad_OAuth_Token')) {
+        throw messages.createError('FrontdoorURLBadOauthToken', undefined, [this.getUsername()]);
+      }
+      throw err;
+    }
   }
 
   /**