From 51e0f0d61c23c46ae349b47118b3bc961e5ccec3 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 25 Jan 2026 12:24:34 +0100
Subject: [PATCH] catalog-backend: module connect error tweaks

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../src/processing/connectEntityProviders.ts       | 10 +++++++---
 .../catalog-backend/src/service/CatalogBuilder.ts  |  2 ++
 .../catalog-backend/src/tests/integration.test.ts  | 14 +++++++++++---
 3 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/plugins/catalog-backend/src/processing/connectEntityProviders.ts b/plugins/catalog-backend/src/processing/connectEntityProviders.ts
index 3955ef017d..f9c14fb978 100644
--- a/plugins/catalog-backend/src/processing/connectEntityProviders.ts
+++ b/plugins/catalog-backend/src/processing/connectEntityProviders.ts
@@ -27,7 +27,7 @@ import {
   EntityProviderMutation,
 } from '@backstage/plugin-catalog-node';
 import type { ExtensionPointFactoryContext } from '@backstage/backend-plugin-api';
-import { assertError } from '@backstage/errors';
+import { ForwardedError } from '@backstage/errors';
 
 export type EntityProviderEntry = {
   provider: EntityProvider;
@@ -118,8 +118,12 @@ export async function connectEntityProviders(
         await provider.connect(connection);
       } catch (error: unknown) {
         if (context) {
-          assertError(error);
-          context.reportModuleStartupFailure({ error });
+          context.reportModuleStartupFailure({
+            error: new ForwardedError(
+              `Failed to connect entity provider '${provider.getProviderName()}'`,
+              error,
+            ),
+          });
           return;
         }
         throw error;
diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts
index ba6f7e28f6..92d07e0ea7 100644
--- a/plugins/catalog-backend/src/service/CatalogBuilder.ts
+++ b/plugins/catalog-backend/src/service/CatalogBuilder.ts
@@ -151,6 +151,8 @@ export type CatalogEnvironment = {
  * - Processors can be added or replaced. These implement the functionality of
  *   reading, parsing, validating, and processing the entity data before it is
  *   persisted in the catalog.
+ *
+ * @internal
  */
 export class CatalogBuilder {
   private readonly env: CatalogEnvironment;
diff --git a/plugins/catalog-backend/src/tests/integration.test.ts b/plugins/catalog-backend/src/tests/integration.test.ts
index b6524a31ab..a30ac62603 100644
--- a/plugins/catalog-backend/src/tests/integration.test.ts
+++ b/plugins/catalog-backend/src/tests/integration.test.ts
@@ -20,7 +20,7 @@ import {
   stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
-import { InputError } from '@backstage/errors';
+import { InputError, NotImplementedError } from '@backstage/errors';
 import { ScmIntegrations } from '@backstage/integration';
 import { LocationSpec } from '@backstage/plugin-catalog-common';
 import {
@@ -321,7 +321,11 @@ class TestHarness {
       providerDatabase,
       providers.map(p => ({
         provider: p,
-        context: { reportModuleStartupFailure: jest.fn() },
+        context: {
+          reportModuleStartupFailure: () => {
+            throw new NotImplementedError();
+          },
+        },
       })),
     );
 
@@ -557,7 +561,11 @@ describe('Catalog Backend Integration', () => {
         },
       ]),
     ).resolves.toBeUndefined();
-    expect(reportFailure).toHaveBeenCalledWith({ error });
+    expect(reportFailure).toHaveBeenCalledWith({
+      error: new Error(
+        "Failed to connect entity provider 'failing'; caused by Error: NOPE",
+      ),
+    });
   });
 
   it('should orphan entities', async () => {