mastra-ai/mastra · error · Error

Comment compounds must be rendered within Comment

Error message

Comment compounds must be rendered within Comment

What it means

useCommentVariant reads the CommentContext that the Comment compound component's Root provides. If the hook runs outside a <Comment.Root>, the context is null and the library throws to fail fast — compound subcomponents (variant-aware pieces) are only valid inside the Comment tree.

Source

Thrown at packages/playground-ui/src/ds/components/Comment/comment-context.ts:9

import { createContext, useContext } from 'react';

export type CommentVariant = 'default' | 'embed';

export const CommentContext = createContext<CommentVariant | null>(null);

export function useCommentVariant(): CommentVariant {
  const variant = useContext(CommentContext);
  if (!variant) throw new Error('Comment compounds must be rendered within Comment');
  return variant;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Wrap the consuming subtree in <Comment.Root>...</Comment.Root>.
2. If a component legitimately needs to work standalone, have it call a nullable variant accessor instead of useCommentVariant (add a useMaybeCommentVariant that returns null).
3. Check for portals/suspense boundaries that detach children from the Root's context provider.
4. Verify imports: the consumer must come from the Comment compound module and be nested under Root in the JSX tree.

Example fix

// before
<Comment.Avatar src={url} /> // outside Root
// after
<Comment.Root>
  <Comment.Avatar src={url} />
</Comment.Root>

// Structural validation: ensure the consumer sits under Comment.Root in the JSX tree.
// At runtime, check the variant before using it:
const variant = useMaybeCommentVariant?.() ?? null; // nullable accessor if available
if (variant === null) console.warn('Comment subcomponent rendered outside <Comment.Root>');

function isInCommentRoot(ctx: CommentVariant | null): ctx is CommentVariant {
  return ctx !== null;
}

try {
  const variant = useCommentVariant(); // hooks can't be in try/catch — validate context instead
} catch {
  // not applicable for hooks; use a nullable context hook and handle null
}

When it happens

Trigger: Rendering a Comment subcomponent (or any consumer of useCommentVariant) without wrapping it in <Comment.Root>; moving a subcomponent out of the Root via a portal or refactoring that broke the JSX nesting.

Common situations: Extracting a variant-aware button into its own file/usage and rendering it standalone; conditional rendering where Root is unmounted but children remain; mis-importing the subcomponent from the barrel without Root.

Related errors

• ${componentName} must be used within EnvironmentVariablesEdi
• useJSONSchemaForm must be used within a JSONSchemaForm.Root
• useJSONSchemaFormField must be used within a JSONSchemaForm.
• useMainSidebar must be used within a MainSidebarProvider.
• useMobileDrawer must be used within a MainSidebarProvider.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/b14603db076f38b3. Report an issue: GitHub.