Troubleshooting

"Cannot find module '@arcyai/sdk/react'"

TypeScript reports:

Cannot find module '@arcyai/sdk/react' or its corresponding type declarations.
There are types at '.../node_modules/@arcyai/sdk/dist/react.d.ts', but this
result could not be resolved under your current 'moduleResolution' setting.
Consider updating to 'node16', 'nodenext', or 'bundler'.

Cause: @arcyai/sdk publishes its ./react and ./styles entry points through the exports field in package.json, not through a top-level main/types field. TypeScript only reads exports when moduleResolution is "node16", "nodenext", or "bundler". If your tsconfig.json still has moduleResolution: "node" (the classic Node10 resolver, and the default in some older create-next-app templates), TypeScript can't see the ./react subpath even though the compiled files exist on disk.

Fix: in tsconfig.json, set:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

"bundler" is the right choice for any app built with Next.js, Vite, or another bundler. Use "nodenext" instead only for code that runs directly under Node (a backend service, a CLI) without a bundling step.

After changing it, restart the TypeScript server in your editor (VS Code: TypeScript: Restart TS Server) so it picks up the new setting, then re-run your typecheck:

npx tsc --noEmit

The error should be gone, and ARCYProvider's props should resolve normally in your editor.

"[ARCY] ARCYProvider is missing a publicKey"

The app throws:

[ARCY] ARCYProvider is missing a publicKey. Set NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY
(pk_...) in this environment's .env. Get your keys at app.arcyai.com > Settings
> API Keys.

Cause: the publicKey prop resolved to an empty string or undefined at runtime. This almost always means the env var your ARCYProvider reads isn't actually set in the environment that's running — most commonly:

• Vite or CRA: your .env.local has NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY, but neither Vite nor CRA exposes NEXT_PUBLIC_-prefixed vars to the browser — only their own convention. You also need VITE_ARCY_PUBLISHABLE_KEY (Vite) or REACT_APP_ARCY_PUBLISHABLE_KEY (CRA) set to the same value. See Framework-specific env vars.
• Local dev with only test keys: your .env.local has NEXT_PUBLIC_ARCY_TEST_PUBLISHABLE_KEY (the dashboard's dev-key convention) but your ARCYProvider only reads the plain NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY name. Read the live key with a fallback to the test key: (process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY || process.env.NEXT_PUBLIC_ARCY_TEST_PUBLISHABLE_KEY)! — this is exactly what arcy init's generated wrapper does.
• Production/preview deploy: the env var is set locally but was never added to your host's environment config (Amplify, Vercel, your container's env, etc). Check Step 5: Deploy to production.

Fix: confirm which environment is actually running, confirm the exact var name your code reads matches the convention for that framework (see the table in Framework-specific env vars), and restart your dev server after editing .env.local — env vars are read at build/start time, not hot-reloaded.

What's next

• Configuration: all ARCYProvider props