{"record":{"id":"63ed4d7038e486d2","repo":"ComposioHQ/composio","slug":"experimental-createlocalworkbenchsession-requires","errorCode":null,"errorMessage":"experimental_createLocalWorkbenchSession requires a session created with workbench.enable: false. The remote workbench and a local sandbox cannot both run for one session.","messagePattern":"experimental_createLocalWorkbenchSession requires a session created with workbench\\.enable: false\\. The remote workbench and a local sandbox cannot both run for one session\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ts/packages/experimental/src/workbench/local-workbench.ts","lineNumber":13,"sourceCode":"import type { Composio, Session } from '@composio/core';\nimport {\n  experimental_createPythonWorkbenchHelperSource,\n  experimental_createWorkbenchEnv,\n} from './shim';\nimport type { LocalWorkbenchSession } from './types';\n\nexport async function experimental_createLocalWorkbenchSession(\n  composio: Composio,\n  session: Session<unknown, unknown, never>\n): Promise<LocalWorkbenchSession> {\n  if (session.workbench?.enable !== false) {\n    throw new Error(\n      'experimental_createLocalWorkbenchSession requires a session created with workbench.enable: false. ' +\n        'The remote workbench and a local sandbox cannot both run for one session.'\n    );\n  }\n\n  const { apiKey, baseURL } = composio.getConfig();\n  if (!apiKey) {\n    throw new Error('A Composio project API key is required to create a local workbench session');\n  }\n\n  const env = experimental_createWorkbenchEnv({\n    sessionId: session.sessionId,\n    backendUrl: baseURL ?? 'https://backend.composio.dev',\n    apiKey,\n  });\n\n  return {\n    env,","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/experimental/src/workbench/local-workbench.ts#L1-L31","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create the session with workbench: { enable: false } before calling experimental_createLocalWorkbenchSession","Check session.workbench?.enable === false before invoking (type-guard the precondition)","Keep one code path per session: remote workbench OR local sandbox, never both"],"exampleFix":"// before\nconst session = await composio.sessions.create({});\nawait experimental_createLocalWorkbenchSession(composio, session);\n// after\nconst session = await composio.sessions.create({ workbench: { enable: false } });\nawait experimental_createLocalWorkbenchSession(composio, session);","handlingStrategy":"validation","validationCode":"if (session.workbench?.enable !== false) {\n  throw new Error('Recreate the session with workbench: { enable: false } before attaching a local sandbox');\n}","typeGuard":"const isLocalWorkbenchCompatible = (s: Session<any, any, never>): boolean => s.workbench?.enable === false;","tryCatchPattern":"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); } }","preventionTips":["Always create sessions with workbench: { enable: false } when planning local sandbox use","Check the flag before calling the experimental API","Never mix remote workbench and local sandbox on one session"],"tags":["workbench","experimental","session","configuration"],"backgroundTag":"invalid-session-configuration","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}