ComposioHQ/composio · error · Error

experimental_createLocalWorkbenchSession requires a session

Error message

experimental_createLocalWorkbenchSession requires a session created with workbench.enable: false. The remote workbench and a local sandbox cannot both run for one session.

What it means

experimental_createLocalWorkbenchSession attaches a local sandbox to a session and therefore requires that session to have been created with workbench.enable: false, so the remote workbench and a local sandbox never run simultaneously. Any other value (including undefined) throws.

Source

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

import type { Composio, Session } from '@composio/core';
import {
  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,

View on GitHub (pinned to 64b1b85502)

Solutions

1. Create the session with workbench: { enable: false } before calling experimental_createLocalWorkbenchSession
2. Check session.workbench?.enable === false before invoking (type-guard the precondition)
3. Keep one code path per session: remote workbench OR local sandbox, never both

Example fix

// before
const session = await composio.sessions.create({});
await experimental_createLocalWorkbenchSession(composio, session);
// after
const session = await composio.sessions.create({ workbench: { enable: false } });
await experimental_createLocalWorkbenchSession(composio, session);

if (session.workbench?.enable !== false) {
  throw new Error('Recreate the session with workbench: { enable: false } before attaching a local sandbox');
}

const isLocalWorkbenchCompatible = (s: Session<any, any, never>): boolean => s.workbench?.enable === false;

try { await experimental_createLocalWorkbenchSession(composio, session); } catch (e) { if (/workbench.enable/.test((e as Error).message)) { const s2 = await composio.sessions.create({ workbench: { enable: false } }); await experimental_createLocalWorkbenchSession(composio, s2); } }

When it happens

Trigger: Calling experimental_createLocalWorkbenchSession(composio, session) where session.workbench?.enable is not exactly false — i.e. the session was created without workbench: { enable: false } or with it enabled.

Common situations: Trying local workbench on a default session (remote workbench on by default); forgetting the workbench flag in session config; SDK upgrade where the flag became mandatory for local mode.

Related errors

• A provider is required when using custom tools with session.
• A Composio project API key is required to create a local wor
• proxy_execute: toolkit is required
• proxy_execute: endpoint is required
• proxy_execute: method must be one of {sorted(_VALID_METHODS)

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