invalid_configuration

HTTP status: N/A (SDK initialization)
Category: SDK configuration

What this error means

The Wocha SDK was initialised with missing or invalid configuration. This typically occurs at client construction time or when required environment variables are absent in production.

Common scenarios: missing tenant/baseUrl, missing apiKey, invalid redirect URI in OAuth apps, or framework adapter env vars not set.

Common causes

• WochaClient created without tenant, baseUrl, or apiKey
• WOCHA_TENANT / WOCHA_API_KEY not set in deployment environment
• OAuth client ID or issuer URL mismatch between app and Console
• Next.js: missing WOCHA_CLIENT_SECRET for confidential BFF client
• Redirect URI in code does not match Console OAuth application settings

How to fix it

1. Run wocha doctor from @wocha/cli to validate local configuration.
2. Copy .env.example to .env.local and fill in all required variables.
3. In Console, verify OAuth application redirect URIs match your app exactly (including trailing slashes).
4. For production, inject secrets via your platform's secret manager — never commit .env files.
5. Use keyless dev mode locally (wocha dev) to auto-provision a development tenant.

Example

import { WochaClient, GreetError } from "@wocha/sdk";
 
function createWochaClient() {
  const tenant = process.env.WOCHA_TENANT;
  const apiKey = process.env.WOCHA_API_KEY;
 
  if (!tenant || !apiKey) {
    throw new GreetError(
      "invalid_configuration",
      "WOCHA_TENANT and WOCHA_API_KEY are required",
      0,
      undefined,
      undefined,
      "sdk",
    );
  }
 
  return new WochaClient({ tenant, apiKey });
}
 
// Next.js — validate env at build time
// wocha.config.ts validates WOCHA_CLIENT_ID, WOCHA_CLIENT_SECRET, WOCHA_ISSUER_URL

# CLI health check
npx @wocha/cli doctor

See also

• Getting started
• @wocha/cli doctor