ComposioHQ/composio · error · Error

A Composio project API key is required to create a local wor

Error message

A Composio project API key is required to create a local workbench session

What it means

experimental_createLocalWorkbenchSession needs a project API key to mint sandbox credentials; if composio.getConfig().apiKey is empty it throws immediately. Anonymous/API-key-less Composio instances cannot create local workbench sessions.

Source

Thrown at ts/packages/experimental/src/workbench/local-workbench.ts:21

  experimental_createPythonWorkbenchHelperSource,
  experimental_createWorkbenchEnv,
} from './shim';
import type { LocalWorkbenchSession } from './types';

export async function experimental_createLocalWorkbenchSession(
  composio: Composio,
  session: Session<unknown, unknown, never>
): Promise<LocalWorkbenchSession> {
  if (session.workbench?.enable !== false) {
    throw new Error(
      'experimental_createLocalWorkbenchSession requires a session created with workbench.enable: false. ' +
        'The remote workbench and a local sandbox cannot both run for one session.'
    );
  }

  const { apiKey, baseURL } = composio.getConfig();
  if (!apiKey) {
    throw new Error('A Composio project API key is required to create a local workbench session');
  }

  const env = experimental_createWorkbenchEnv({
    sessionId: session.sessionId,
    backendUrl: baseURL ?? 'https://backend.composio.dev',
    apiKey,
  });

  return {
    env,
    helperSource: experimental_createPythonWorkbenchHelperSource(),
  };
}

View on GitHub (pinned to 64b1b85502)

Solutions

1. Set COMPOSIO_API_KEY or pass apiKey explicitly when constructing Composio
2. Verify the env var name and that it is loaded (dotenv, CI secrets) before creating the session
3. Fail fast at startup: if local workbench is required, assert the API key exists during boot

Example fix

// before
const composio = new Composio({}); // apiKey undefined
// after
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! });

if (!process.env.COMPOSIO_API_KEY) throw new Error('COMPOSIO_API_KEY is required for local workbench sessions');

const hasApiKey = (c: Composio): boolean => Boolean(c.getConfig().apiKey);

catch (e) { if ((e as Error).message.includes('project API key')) { /* load env, reconstruct Composio, retry */ } throw e; }

When it happens

Trigger: Constructing Composio without an apiKey (relying on some other auth mechanism) and then calling experimental_createLocalWorkbenchSession.

Common situations: Missing COMPOSIO_API_KEY env var; initializing Composio({ apiKey: undefined }) due to a typo'd env name; running in CI without secrets configured.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• experimental_createLocalWorkbenchSession requires a session
• proxy() requires an authenticated Composio user session.
• Failed to parse connected account ACL update params
• Trigger subscription error
• %s is required

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/2dfb6d18fb8ae52a. Report an issue: GitHub.