n8n-io/n8n · error · Error

--build-via-mcp requires LangSmith experiment tracking — set

Error message

--build-via-mcp requires LangSmith experiment tracking — set LANGSMITH_API_KEY. The no-LangSmith direct loop does not support MCP builds.

What it means

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.

Source

Thrown at packages/@n8n/instance-ai/evaluations/cli/args.ts:194

	// --build-via-mcp checks first: they give clearer guidance than the generic
	// --delete-prebuilt-workflows check below when both are combined.
	if (validated.buildViaMcp && validated.prebuiltWorkflows) {
		throw new Error(
			'--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.',
		);
	}
	if (validated.buildViaMcp && validated.deletePrebuiltWorkflows) {
		throw new Error(
			'--delete-prebuilt-workflows applies to --prebuilt-workflows. --build-via-mcp already cleans up the workflows it builds unless --keep-workflows is set.',
		);
	}
	// MCP builds are LangSmith-only: the keyless direct loop parallelizes
	// iterations without the lane allocator, so its 4-per-lane build cap applies
	// PER ITERATION — concurrent `claude` sessions would scale with
	// lanes × iterations × 4 and flood the shared Anthropic budget. Fail fast
	// instead of teaching the direct loop (tech debt slated for removal) MCP builds.
	if (validated.buildViaMcp && !process.env.LANGSMITH_API_KEY) {
		throw new Error(
			'--build-via-mcp requires LangSmith experiment tracking — set LANGSMITH_API_KEY. The no-LangSmith direct loop does not support MCP builds.',
		);
	}
	// Build knobs without --build-via-mcp would parse fine and then be silently
	// ignored — the run would look like it honored them. Fail loudly instead.
	if (!validated.buildViaMcp && raw.buildOnlyFlags.length > 0) {
		throw new Error(
			`${[...new Set(raw.buildOnlyFlags)].join(', ')} only take${raw.buildOnlyFlags.length === 1 ? 's' : ''} effect with --build-via-mcp — pass it, or drop the flag(s).`,
		);
	}
	if (validated.deletePrebuiltWorkflows && !validated.prebuiltWorkflows) {
		throw new Error('--delete-prebuilt-workflows requires --prebuilt-workflows');
	}
	if (validated.deletePrebuiltWorkflows && validated.keepWorkflows) {
		throw new Error('--delete-prebuilt-workflows cannot be used with --keep-workflows');
	}
	if (validated.source === 'langtracer' && !validated.suite) {
		throw new Error('--source langtracer requires --suite <slug>');

View on GitHub (pinned to 5ac6606e81)

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.

Example fix

// before
pnpm eval:instance-ai --build-via-mcp --base-url http://localhost:5678
// after
export LANGSMITH_API_KEY=lsv2_pt_...
pnpm eval:instance-ai --build-via-mcp --base-url http://localhost:5678

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking the eval CLI with --build-via-mcp:
if (!process.env.LANGSMITH_API_KEY) {
  throw new Error('LANGSMITH_API_KEY must be set for --build-via-mcp runs.');
}

Prevention

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)"`.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/a592ebe0d7f3579e. Report an issue: GitHub.