What causes "Unknown flag: ${flagName}" in n8n-io/n8n?

n8n-io/n8n · error · Error

Unknown flag: ${flagName}

Error message

Unknown flag: ${flagName}

What it means

Thrown by the default case of parseRawArgs() (args.ts:510) when an argument starts with -- but does not match any known flag case. The flag name is sanitized by splitting on '=' and taking only the first segment before echoing, so that a value payload (which may contain a secret like --password=hunter2 or an accidentally pasted token) is never leaked into terminal or CI logs. This is a deliberate security-conscious design choice noted in the source comment.

Source

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

				result.buildMcpTimeoutMs = parseIntArg(argv, i, '--build-mcp-timeout-ms');
				result.buildOnlyFlags.push(arg);
				i++;
				break;

			case '--build-timeout-ms':
				result.buildTimeoutMs = parseIntArg(argv, i, '--build-timeout-ms');
				result.buildOnlyFlags.push(arg);
				i++;
				break;

			default:
				// Fail loudly on unknown flags. Strip any =value payload before
				// echoing and drop positional values entirely — raw CLI input
				// may contain secrets (e.g. --password=... or an accidentally
				// pasted token) that would otherwise leak into terminal/CI logs.
				if (arg.startsWith('--')) {
					const flagName = arg.split('=', 1)[0];
					throw new Error(`Unknown flag: ${flagName}`);
				}
				throw new Error('Unexpected positional argument');
		}
	}

	return result;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function nextArg(argv: string[], currentIndex: number, flagName: string): string {
	const value = argv[currentIndex + 1];
	if (value === undefined || value.startsWith('--')) {
		throw new Error(`Missing value for ${flagName}`);
	}
	return value;

View on GitHub (pinned to 5ac6606e81)

Solutions

Check the flag spelling against the known cases in parseRawArgs() (args.ts:359-501): --timeout-ms, --base-url, --email, --password, --verbose, --filter, --exclude, --prebuilt-workflows, --keep-workflows, --delete-prebuilt-workflows, --output-dir, --iterations, --dataset, --concurrency, --experiment-name, --pin-ai-roots, --tier, --baseline-prefix, --source, --suite, --build-via-mcp, --mcp-server, --build-cwd, --build-max-attempts, --build-mcp-timeout-ms, --build-timeout-ms.
Use the correct tool: some flags (e.g. --manifest, --builder, --append) belong to build-mcp-manifest, not eval:instance-ai.
Correct the typo or remove the unrecognized flag.

Example fix

// before
pnpm eval:instance-ai --buld-via-mcp --base-url http://localhost:5678
// after
pnpm eval:instance-ai --build-via-mcp --base-url http://localhost:5678

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_FLAGS = new Set(['--timeout-ms','--base-url','--email','--password','--verbose','--filter','--exclude','--prebuilt-workflows','--keep-workflows','--delete-prebuilt-workflows','--output-dir','--iterations','--dataset','--concurrency','--experiment-name','--pin-ai-roots','--tier','--baseline-prefix','--source','--suite','--build-via-mcp','--mcp-server','--build-cwd','--build-max-attempts','--build-mcp-timeout-ms','--build-timeout-ms']);
function validateKnownFlags(args: string[]): void {
  for (const a of args) {
    if (a.startsWith('--') && !KNOWN_FLAGS.has(a.split('=',1)[0])) {
      throw new Error(`Unknown flag: ${a.split('=',1)[0]}`);
    }
  }
}

Prevention

Keep a documented list of supported eval CLI flags in your runbook.
Run commands through a wrapper that validates flags before exec.
Use shell completion or a CLI generator if the flag set grows.
Never paste a flag from a different tool without checking it exists here.

When it happens

Trigger: Passing any unrecognized long flag to the eval CLI, e.g. --verbose-mode instead of --verbose, or a typo like --buld-via-mcp. Also triggered by flags that belong to a different tool (e.g. build-mcp-manifest flags passed to eval:instance-ai). The flag name is stripped of any =value before being reported.

Common situations: Typo in a flag name, using a flag from a different CLI in this repo, or referencing a flag that was renamed or removed in a version change. The error message intentionally does not echo the value portion for security.

Related errors

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