{"record":{"id":"055ccedc6a8a5f70","repo":"ComposioHQ/composio","slug":"custom-tool-slugs-are-not-supported-in-preload-too-055cce","errorCode":null,"errorMessage":"Custom tool slugs are not supported in preload.tools: ${customPreloadSlugs.join(', ')}. Set preload: true on the SDK custom tool or custom toolkit definition instead.","messagePattern":"Custom tool slugs are not supported in preload\\.tools: (.+?)\\. Set preload: true on the SDK custom tool or custom toolkit definition instead\\.","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"ts/packages/core/src/models/CustomTool.ts","lineNumber":631,"sourceCode":"): void {\n  if (!preloadTools || preloadTools === PRELOAD_TOOLS_ALL) {\n    return;\n  }\n\n  const customPreloadSlugs = preloadTools.filter(slug => {\n    const normalized = slug.toUpperCase();\n    return (\n      // Top-level preload.tools is only for Composio-managed tool slugs.\n      // Custom tools use `preload: true` on their SDK definitions instead.\n      normalized.startsWith(LOCAL_TOOL_PREFIX) ||\n      customToolsMap?.byOriginalSlug.has(normalized) ||\n      customToolsMap?.ambiguousOriginalSlugs?.has(normalized) ||\n      customToolsMap?.byFinalSlug.has(normalized)\n    );\n  });\n\n  if (customPreloadSlugs.length) {\n    throw new ValidationError(\n      `Custom tool slugs are not supported in preload.tools: ${customPreloadSlugs.join(\n        ', '\n      )}. Set preload: true on the SDK custom tool or custom toolkit definition instead.`\n    );\n  }\n}\n\n/**\n * Resolve custom tools that the SDK should expose directly from session.tools().\n *\n * @internal\n */\nexport function getPreloadedCustomToolSlugs(\n  customToolsMap: CustomToolsMap | undefined,\n  defaultPreload = false\n): string[] {\n  if (!customToolsMap) {\n    return [];","sourceCodeStart":613,"sourceCodeEnd":649,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/core/src/models/CustomTool.ts#L613-L649","documentation":"The SDK rejects session preload configurations that name custom tools directly in preload.tools. Custom tools must opt into preloading via `preload: true` on their own definition, because the preload list only accepts backend tool slugs.","triggerScenarios":"Passing a session config whose preload.tools array contains a slug that resolves to an SDK custom tool or custom toolkit tool (checked against the custom tools map, including ambiguous original slugs). Raised from assertNoCustomToolSlugsInPreload during prepareInlineCustomTools.","commonSituations":"Migrating a config that preloaded a standard tool and swapping in a custom tool slug; assuming preload.tools accepts anything in the tools list; referencing a custom tool by original slug that also exists in the map.","solutions":["Remove the custom tool slug from preload.tools and set `preload: true` on the custom tool definition","For a custom toolkit, set preload: true on the toolkit definition instead","Verify remaining preload.tools entries are ordinary (non-custom) tool slugs"],"exampleFix":"// before\nawait composio.sessions.create({ preload: { tools: ['my_custom_tool'] } });\n// after\nconst tool = defineTool({ slug: 'my_custom_tool', preload: true, /* ... */ });\nawait composio.sessions.create({});","handlingStrategy":"validation","validationCode":"const customSlugs = new Set([...customTools.map(t => t.slug.toUpperCase()), ...customToolsMap?.ambiguousOriginalSlugs ?? []]);\nconst bad = (preload.tools ?? []).filter(s => customSlugs.has(s.toUpperCase()));\nif (bad.length) throw new Error(`Custom slugs in preload.tools: ${bad.join(', ')}`);","typeGuard":"const preloadIsSafe = (preloadTools: string[], customSlugs: Set<string>): boolean =>\n  preloadTools.every(s => !customSlugs.has(s.toUpperCase()));","tryCatchPattern":"try { await composio.sessions.create(cfg); } catch (e) { if (e instanceof ValidationError && e.message.includes('preload.tools')) { cfg.preload.tools = []; delete cfg.preload; /* set preload on tool instead */ } }","preventionTips":["Never put custom tool slugs in preload.tools","Set preload: true on the defineTool call","Document that preload.tools is backend-tools-only"],"tags":["custom-tools","preload","session","validation","typescript"],"backgroundTag":"invalid-configuration-option","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}