Fix React SDK issues

Use this guide as a checklist when your React integration fails to initialize, connect, or fetch credentials. Each section includes the exact error or symptom, the root cause, and the fix.

SDK not initialized

Error


OrgaAI must be initialized before use. Call OrgaAI.init() first.

Cause – OrgaAI.init() did not run before rendering hooks or components.

Fix

Run OrgaAI.init() once at bootstrap (e.g., inside app/providers/OrgaClientProvider.tsx).
Provide fetchSessionConfig or sessionConfigEndpoint.
Optionally set model, voice, and logLevel.

app/providers/OrgaClientProvider.tsx


import { OrgaAI, OrgaAIProvider } from '@orga-ai/react';
 
OrgaAI.init({
  fetchSessionConfig: async () => {
    const res = await fetch('/api/orga-client-secrets');
    return res.json();
  },
  model: 'orga-1-beta',
  voice: 'alloy',
});
 
export function OrgaClientProvider({ children }: { children: React.ReactNode }) {
  return <OrgaAIProvider>{children}</OrgaAIProvider>;
}

Hook used outside provider

Error


useOrgaAI must be used within an OrgaAIProvider

Cause – Components calling useOrgaAI() are not wrapped in <OrgaAIProvider>.

Fix – Wrap your root layout:

app/layout.tsx


import { OrgaClientProvider } from './providers/OrgaClientProvider';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <OrgaClientProvider>{children}</OrgaClientProvider>
      </body>
    </html>
  );
}

Missing environment variables

Symptom – API route returns 401 or 500 when fetching session config.

Fix

Ensure .env.local contains:


ORGA_API_KEY=sk_orga_ai_*****************************

Restart the dev server so process.env picks up the new values.

Incompatible React version

Symptom – Build fails or hooks behave unpredictably.

Fix – Upgrade to React 18.2+:


npm install react@18 react-dom@18

General debugging tips

Enable logLevel: 'debug' inside OrgaAI.init() to see negotiation steps.
Re-run the React tutorial to confirm setup order.
Validate your backend proxy with curl http://localhost:5000/api/orga-client-secrets.

Still blocked? Open an issue in the Orga AI GitHub repo .