n8n-io/n8n · error · Error

--iterations must be >= 1

Error message

--iterations must be >= 1

What it means

Thrown by parseArgs() (build-mcp-manifest.ts:230) when the parsed --iterations value (or -n shorthand) is less than 1. Iterations controls how many builds are produced per slug; zero or negative iterations is meaningless. Note: parseIntArg accepts any integer including 0 or negatives (parseInt('-1') is -1), so this boundary check catches non-positive values that parseIntArg would otherwise let through. The check fires after the parse loop.

Source

Thrown at packages/@n8n/instance-ai/evaluations/cli/build-mcp-manifest.ts:230

			}
			case '--suite':
				result.suite = nextArg(argv, i, arg);
				i += 2;
				break;
			case '-h':
			case '--help':
				return { helpRequested: true };
			default:
				if (arg.startsWith('--')) {
					throw new Error(`Unknown flag: ${arg.split('=', 1)[0]} (use --help)`);
				}
				result.slugs.push(arg);
				i += 1;
				break;
		}
	}

	if (result.iterations < 1) throw new Error('--iterations must be >= 1');
	if (result.concurrency < 1) throw new Error('--concurrency must be >= 1');
	if (result.maxAttempts < 1) throw new Error('--max-attempts must be >= 1');
	if (result.source === 'langtracer' && !result.suite) {
		throw new Error('--source langtracer requires --suite <slug>');
	}

	mkdirSync(result.outputDir, { recursive: true });
	if (!result.manifestPath) result.manifestPath = join(result.outputDir, 'manifest.json');
	if (!result.logDir) result.logDir = join(result.outputDir, 'logs');
	const base = result.manifestPath.replace(/\.json$/, '');
	result.statsPath = `${base}-stats.json`;
	mkdirSync(result.logDir, { recursive: true });

	return { helpRequested: false, args: result };
}

function readJson(path: string, label: string): unknown {
	const content = readFileSync(path, 'utf-8');

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Pass a positive integer: --iterations 1 or higher.
2. If computing iterations dynamically, guard the value: `ITERATIONS=$(( COUNT > 0 ? COUNT : 1 ))` before passing.
3. Verify the shell variable is set and positive: `echo "${ITERATIONS:?unset}"`.

Example fix

// before
pnpm eval:build-mcp-manifest --iterations 0
// after
pnpm eval:build-mcp-manifest --iterations 1

function validateIterations(args: string[]): void {
  for (let i = 0; i < args.length; i++) {
    if ((args[i] === '-n' || args[i] === '--iterations')) {
      const v = Number(args[i + 1]);
      if (!Number.isInteger(v) || v < 1) {
        throw new Error(`--iterations must be >= 1, got: ${args[i + 1]}`);
      }
    }
  }
}

function isPositiveInt(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 1;
}

When it happens

Trigger: Passing `--iterations 0`, `-n 0`, `--iterations -1`, or a shell variable that resolved to a non-positive integer. parseIntArg only rejects NaN, so 0/negative reach this boundary check.

Common situations: A shell variable for iteration count is unset and defaulted to 0, a script computes iterations dynamically and produces 0 in some branch, or a typo passes a negative number.

Related errors

• --source must be "disk" or "langtracer"
• Unknown flag: ${arg.split('=', 1)[0]} (use --help)
• --concurrency must be >= 1
• --delete-prebuilt-workflows applies to --prebuilt-workflows.
• ${[...new Set(raw.buildOnlyFlags)].join(', ')} only take${ra

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