core-api: more informative error for missing ApiContext

.changeset/gentle-buses-exist.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core-api': patch
+'@backstage/core': patch
+---
+
+More informative error message for missing ApiContext.

packages/core-api/src/apis/system/ApiProvider.test.tsx

@@ -108,11 +108,11 @@ describe('ApiProvider', () => {
       withLogCollector(['error'], () => {
         expect(() => {
           render(<MyHookConsumer />);
-        }).toThrow('No ApiProvider available in react context');
+        }).toThrow(/^No ApiProvider available in react context. /);
       }).error,
     ).toEqual([
       expect.stringMatching(
-        /^Error: Uncaught \[Error: No ApiProvider available in react context\]/,
+        /^Error: Uncaught \[Error: No ApiProvider available in react context. /,
       ),
       expect.stringMatching(
         /^The above error occurred in the <MyHookConsumer> component/,
@@ -123,11 +123,11 @@ describe('ApiProvider', () => {
       withLogCollector(['error'], () => {
         expect(() => {
           render(<MyHocConsumer />);
-        }).toThrow('No ApiProvider available in react context');
+        }).toThrow(/^No ApiProvider available in react context. /);
       }).error,
     ).toEqual([
       expect.stringMatching(
-        /^Error: Uncaught \[Error: No ApiProvider available in react context\]/,
+        /^Error: Uncaught \[Error: No ApiProvider available in react context. /,
       ),
       expect.stringMatching(
         /^The above error occurred in the <withApis\(Component\)> component/,

packages/core-api/src/apis/system/ApiProvider.tsx

@@ -24,6 +24,12 @@ import PropTypes from 'prop-types';
 import { ApiRef, ApiHolder, TypesToApiRefs } from './types';
 import { ApiAggregator } from './ApiAggregator';
 
+const missingHolderMessage =
+  'No ApiProvider available in react context. ' +
+  'A common cause of this error is that multiple versions of @backstage/core-api are installed. ' +
+  `You can check if that is the case using 'yarn backstage-cli versions:check', and can in many cases ` +
+  `fix the issue either with the --fix flag or using 'yarn backstage-cli versions:bump'`;
+
 type ApiProviderProps = {
   apis: ApiHolder;
   children: ReactNode;
@@ -50,7 +56,7 @@ export function useApiHolder(): ApiHolder {
   const apiHolder = useContext(Context);
 
   if (!apiHolder) {
-    throw new Error('No ApiProvider available in react context');
+    throw new Error(missingHolderMessage);
   }
 
   return apiHolder;
@@ -74,7 +80,7 @@ export function withApis<T>(apis: TypesToApiRefs<T>) {
       const apiHolder = useContext(Context);
 
       if (!apiHolder) {
-        throw new Error('No ApiProvider available in react context');
+        throw new Error(missingHolderMessage);
       }
 
       const impls = {} as T;