improve blocks error messages

MIGRATION.md

@@ -1097,6 +1097,8 @@ import * as ComponentStories from './some-component.stories';
 <Story of={ComponentStories.Primary} />
 ```
 
+(Note the `of` prop is only supported if you change your MDX files to plain `.mdx`, it's not supported in `.stories.mdx` files)
+
 You can create as many docs entries as you like for a given component. By default the docs entry will be named the same as the `.mdx` file (e.g. `Introduction.mdx` becomes `Introduction`). If the docs file is named the same as the component (e.g. `Button.mdx`, it will use the default autodocs name (`"Docs"`) and override autodocs).
 
 By default docs entries are listed first for the component. You can sort them using story sorting.
@@ -1119,7 +1121,7 @@ Additionally to changing the docs information architecture, we've updated the AP
 
 **General changes**
 
-- Each block now uses `of={}` as a primary API -- where the argument to the `of` prop is a CSF or story _export_.
+- Each block now uses `of={}` as a primary API -- where the argument to the `of` prop is a CSF or story _export_. The `of` prop is only supported in plain `.mdx` files and not `.stories.mdx` files.
 
 - When you've attached to a CSF file (with the `Meta` block, or in Autodocs), you can drop the `of` and the block will reference the first story or the CSF file as a whole.
 

code/lib/preview-api/src/modules/preview-web/docs-context/DocsContext.ts

@@ -12,6 +12,7 @@ import type {
 } from '@storybook/types';
 import type { Channel } from '@storybook/channels';
 
+import dedent from 'ts-dedent';
 import type { StoryStore } from '../../store';
 import { prepareMeta } from '../../store';
 import type { DocsContextProps } from './DocsContextProps';
@@ -85,7 +86,9 @@ export class DocsContext<TRenderer extends Renderer> implements DocsContextProps
   referenceMeta(metaExports: ModuleExports, attach: boolean) {
     const resolved = this.resolveModuleExport(metaExports);
     if (resolved.type !== 'meta')
-      throw new Error('Cannot reference a non-meta or module export in <Meta of={} />');
+      throw new Error(
+        '<Meta of={} /> must reference a CSF file module export or meta export. Did you mistakenly reference your component instead of your CSF file?'
+      );
 
     if (attach) this.attachCSFFile(resolved.csfFile);
   }
@@ -160,11 +163,12 @@ export class DocsContext<TRenderer extends Renderer> implements DocsContextProps
 
     if (validTypes.length && !validTypes.includes(resolved.type as TType)) {
       const prettyType = resolved.type === 'component' ? 'component or unknown' : resolved.type;
-      throw new Error(
-        `Invalid value passed to the 'of' prop. The value was resolved to a '${prettyType}' type but the only types for this block are: ${validTypes.join(
-          ', '
-        )}`
-      );
+      throw new Error(dedent`Invalid value passed to the 'of' prop. The value was resolved to a '${prettyType}' type but the only types for this block are: ${validTypes.join(
+        ', '
+      )}.
+        - Did you pass a component to the 'of' prop when the block only supports a story or a meta?
+        - ... or vice versa?
+        - Did you pass a story, CSF file or meta to the 'of' prop that is not indexed, ie. is not targeted by the 'stories' globs in the main configuration?`);
     }
 
     switch (resolved.type) {