Troubleshooting

Most integration issues with the React SDK come from initialization or provider setup.
Use this checklist when debugging.

SDK not initialized

Error message:


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

Cause:
OrgaAI.init() has not been called before rendering components that depend on it,
or required configuration values are missing.

Fix:

Make sure OrgaAI.init() runs once before your React tree mounts.
(Typically in app/providers/OrgaClientProvider.tsx.)
Provide the required configuration:
- fetchSessionConfig or sessionConfigEndpoint
- model and voice (optional)
- A valid logLevel if debugging

Example:

app/providers/OrgaClientProvider.tsx


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

Hook used outside Provider

Error message:


useOrgaAI must be used within an OrgaAIProvider

Cause:
Your component tree is not wrapped in <OrgaAIProvider>.
The hooks rely on React context provided at the top level.

Fix: Wrap your app (or at least the portion using Orga hooks) inside the provider.

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:
Your backend route fails or returns 401 errors when fetching session config.

Fix: Verify .env includes:


ORGA_API_KEY=sk_orga_ai_*****************************
USER_EMAIL=your_email_here

and that your backend endpoint uses them correctly when calling
@orga-ai/node or hitting the REST API.

Incompatible React version

The SDK requires React 18.2+ for concurrent‑safe hooks and context APIs.
If your project is on an older version, upgrade React and ReactDOM:


npm install react@18 react-dom@18

Still stuck?

Revisit the Quick Start to verify setup order.
Run your app with logLevel: 'debug' in OrgaAI.init() to inspect configuration logs.
Check open issues or examples in the Orga AI GitHub repo .