{"record":{"id":"a592ebe0d7f3579e","repo":"n8n-io/n8n","slug":"build-via-mcp-requires-langsmith-experiment-trac","errorCode":null,"errorMessage":"--build-via-mcp requires LangSmith experiment tracking — set LANGSMITH_API_KEY. The no-LangSmith direct loop does not support MCP builds.","messagePattern":"--build-via-mcp requires LangSmith experiment tracking — set LANGSMITH_API_KEY\\. The no-LangSmith direct loop does not support MCP builds\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/instance-ai/evaluations/cli/args.ts","lineNumber":194,"sourceCode":"\t// --build-via-mcp checks first: they give clearer guidance than the generic\n\t// --delete-prebuilt-workflows check below when both are combined.\n\tif (validated.buildViaMcp && validated.prebuiltWorkflows) {\n\t\tthrow new Error(\n\t\t\t'--build-via-mcp is incompatible with --prebuilt-workflows. --build-via-mcp builds fresh workflows via the MCP server on each lane; --prebuilt-workflows verifies existing ones.',\n\t\t);\n\t}\n\tif (validated.buildViaMcp && validated.deletePrebuiltWorkflows) {\n\t\tthrow new Error(\n\t\t\t'--delete-prebuilt-workflows applies to --prebuilt-workflows. --build-via-mcp already cleans up the workflows it builds unless --keep-workflows is set.',\n\t\t);\n\t}\n\t// MCP builds are LangSmith-only: the keyless direct loop parallelizes\n\t// iterations without the lane allocator, so its 4-per-lane build cap applies\n\t// PER ITERATION — concurrent `claude` sessions would scale with\n\t// lanes × iterations × 4 and flood the shared Anthropic budget. Fail fast\n\t// instead of teaching the direct loop (tech debt slated for removal) MCP builds.\n\tif (validated.buildViaMcp && !process.env.LANGSMITH_API_KEY) {\n\t\tthrow new Error(\n\t\t\t'--build-via-mcp requires LangSmith experiment tracking — set LANGSMITH_API_KEY. The no-LangSmith direct loop does not support MCP builds.',\n\t\t);\n\t}\n\t// Build knobs without --build-via-mcp would parse fine and then be silently\n\t// ignored — the run would look like it honored them. Fail loudly instead.\n\tif (!validated.buildViaMcp && raw.buildOnlyFlags.length > 0) {\n\t\tthrow new Error(\n\t\t\t`${[...new Set(raw.buildOnlyFlags)].join(', ')} only take${raw.buildOnlyFlags.length === 1 ? 's' : ''} effect with --build-via-mcp — pass it, or drop the flag(s).`,\n\t\t);\n\t}\n\tif (validated.deletePrebuiltWorkflows && !validated.prebuiltWorkflows) {\n\t\tthrow new Error('--delete-prebuilt-workflows requires --prebuilt-workflows');\n\t}\n\tif (validated.deletePrebuiltWorkflows && validated.keepWorkflows) {\n\t\tthrow new Error('--delete-prebuilt-workflows cannot be used with --keep-workflows');\n\t}\n\tif (validated.source === 'langtracer' && !validated.suite) {\n\t\tthrow new Error('--source langtracer requires --suite <slug>');","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/instance-ai/evaluations/cli/args.ts#L176-L212","documentation":"Thrown by parseCliArgs() when --build-via-mcp is set but the LANGSMITH_API_KEY environment variable is absent. MCP builds drive `claude -p` against the per-lane MCP server, and the run is gated on LangSmith experiment tracking because the keyless direct loop parallelizes iterations without the lane allocator — its 4-per-lane build cap applies per iteration, so concurrent `claude` sessions would scale with lanes × iterations × 4 and flood the shared Anthropic budget. The parser fails fast rather than teaching the direct loop (tech debt slated for removal) how to handle MCP builds.","triggerScenarios":"Running the eval CLI with --build-via-mcp in a shell or CI job where LANGSMITH_API_KEY is not exported. The check at args.ts:193 reads process.env.LANGSMITH_API_KEY directly; an empty string is falsy and also trips it.","commonSituations":"Running locally without sourcing the .env.local file, a CI secret that was renamed or scoped to a different job, or a Docker/container run that forgot to pass -e LANGSMITH_API_KEY. Also triggered when the key is set in a different shell session than the one launching the eval.","solutions":["Export LANGSMITH_API_KEY in the shell or CI environment before invoking the eval CLI.","Load it from your dotenv file: `dotenvx run -f .env.local -- pnpm eval:instance-ai --build-via-mcp ...`.","For CI, ensure the LANGSMITH_API_KEY secret is added to the job's environment block and that the step actually depends on it.","Verify the value is non-empty: `echo \"${LANGSMITH_API_KEY:?unset}\"` before the run."],"exampleFix":"// before\npnpm eval:instance-ai --build-via-mcp --base-url http://localhost:5678\n// after\nexport LANGSMITH_API_KEY=lsv2_pt_...\npnpm eval:instance-ai --build-via-mcp --base-url http://localhost:5678","handlingStrategy":"validation","validationCode":"// Before invoking the eval CLI with --build-via-mcp:\nif (!process.env.LANGSMITH_API_KEY) {\n  throw new Error('LANGSMITH_API_KEY must be set for --build-via-mcp runs.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always source .env.local (dotenvx run -f .env.local -- ...) before MCP eval runs.","In CI, add LANGSMITH_API_KEY as a required secret and assert it in a pre-step.","Validate env at script entry: `node -e \"process.env.LANGSMITH_API_KEY || process.exit(1)\"`."],"tags":["cli","environment","langsmith","instance-ai","secrets"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}