vercel/ai · error

`useSyncUIState` must be used inside an <AI> provider.

Error message

`useSyncUIState` must be used inside an <AI> provider.

What it means

useSyncUIState is a React hook in the RSC package that requires a surrounding <AI> provider from `ai/rsc`. It reads a sync callback from an internal React context, which is only populated when the component tree is rendered inside <AI>. When the context value is null (no provider), the hook throws to prevent calling a sync function that does not exist.

Source

Thrown at packages/rsc/src/shared-client/context.tsx:217

  } else {
    return [state[0][args[0]], setter];
  }
}

export function useActions<AI extends AIProvider = any>() {
  type T = InferActions<AI, any>;

  const actions = React.useContext<T>(InternalActionProvider);
  return actions;
}

export function useSyncUIState() {
  const syncUIState = React.useContext<() => Promise<void>>(
    InternalSyncUIStateProvider,
  );

  if (syncUIState === null) {
    throw new Error('`useSyncUIState` must be used inside an <AI> provider.');
  }

  return syncUIState;
}

export { useAIState };

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Wrap the component using the hook in the <AI> provider from `ai/rsc`
2. Check that the component is rendered as a child of <AI>, not a sibling or in a different React root
3. If the component renders into a portal, ensure the portal is created inside the <AI> subtree

Example fix

// before
export default function Page() {
  return <MyComponent />; // uses useSyncUIState
}
// after
import { AI } from 'ai/rsc';
export default function Page() {
  return (
    <AI>
      <MyComponent />
    </AI>
  );
}

function useSafeSyncUIState() {
  const inProvider = React.useContext(InternalSyncUIStateProvider) !== null;
  if (!inProvider) throw new Error('useSyncUIState requires <AI> provider');
  return useSyncUIState();
}

When it happens

Trigger: Calling useSyncUIState() in a component that is not a descendant of <AI>, e.g. rendering the component outside the provider, forgetting to wrap the app, or using the hook in a different React root (portal/second root) that has no provider.

Common situations: Adding a component that uses the hook to a page where the <AI> wrapper was removed during refactoring; rendering part of the UI in a separate root; copying hook usage from docs without adding the provider in a new route.

Related errors

• Unsupported React version.
• `useUIState` must be used inside an <AI> provider.
• ${method}: Value stream is already closed.
• ${method}: Value stream is locked and cannot be updated.
• .append(): The current value is not a string. Received: ${ty

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ff634d4d3a4e9fb9. Report an issue: GitHub.