n8n-io/n8n · error · Error

only take effect with --build-via-mcp — pass it, or drop…

Error message

${[...new Set(raw.buildOnlyFlags)].join(', ')} only take${raw.buildOnlyFlags.length === 1 ? 's' : ''} effect with --build-via-mcp — pass it, or drop the flag(s).

What it means

Thrown by parseCliArgs() when build-only flags (--mcp-server, --build-cwd, --build-max-attempts, --build-mcp-timeout-ms, --build-timeout-ms) are passed without --build-via-mcp. These flags are collected into raw.buildOnlyFlags during raw parsing; without --build-via-mcp they would parse and validate successfully but then be silently ignored, making the run look like it honored them. The parser fails loudly to prevent this silent misuse.

Solutions

1. Add --build-via-mcp to the command if you intend MCP builds.
2. Remove the offending build-only flag(s) listed in the error message if you do not want MCP builds.
3. Review the list of build-only flags in parseRawArgs() (args.ts cases for --mcp-server, --build-cwd, --build-max-attempts, --build-mcp-timeout-ms, --build-timeout-ms) to identify all of them.

Example fix

// before
pnpm eval:instance-ai --build-max-attempts 5 --build-timeout-ms 600000 --base-url http://localhost:5678
// after (MCP build intended)
pnpm eval:instance-ai --build-via-mcp --build-max-attempts 5 --build-timeout-ms 600000 --base-url http://localhost:5678
// after (no MCP build — drop the knobs)
pnpm eval:instance-ai --base-url http://localhost:5678

const BUILD_ONLY_FLAGS = ['--mcp-server','--build-cwd','--build-max-attempts','--build-mcp-timeout-ms','--build-timeout-ms'];
function validateBuildFlags(args: string[]): void {
  const hasBuildViaMcp = args.includes('--build-via-mcp');
  const offending = BUILD_ONLY_FLAGS.filter((f) => args.includes(f));
  if (!hasBuildViaMcp && offending.length > 0) {
    throw new Error(`${offending.join(', ')} require --build-via-mcp`);
  }
}

When it happens

Trigger: Passing any of the build-knob flags (e.g. --build-max-attempts 5, --build-timeout-ms 600000) on the command line without also passing --build-via-mcp. The deduplicated set of offending flags is joined into the message; singular vs plural verb agreement is chosen by the count.

Common situations: A developer tunes build parameters for a regular (Instance AI orchestrator) run, not realizing those knobs only apply to MCP builds. Or a flag is left over after removing --build-via-mcp from a previously MCP-only command.

Related errors

• --delete-prebuilt-workflows applies to…
• --delete-prebuilt-workflows cannot be used with…
• --delete-prebuilt-workflows requires --prebuilt-workflows
• --concurrency must be >= 1
• Flag needs a value

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

Appendix: source

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

	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>');
	}

	// In langtracer mode, default the dataset + baseline to a suite-scoped, eval-tagged
	// name so runs don't pollute the shared cohort and re-runs upsert one stable dataset.
	let dataset = validated.dataset;
	let datasetAutoForked = false;
	let baselinePrefix = validated.baselinePrefix;

View on GitHub (pinned to 5ac6606e81)