n8n-io/n8n · error · Error

replacements must be a JSON array of

Error message

replacements must be a JSON array of {old_str, new_str} objects, but received an invalid JSON string.

What it means

Input-validation error from parseStrReplacements in the text-editor tool. It fires when the replacements argument arrived as a string but JSON.parse failed, so the model passed malformed JSON instead of the expected array of {old_str, new_str} objects. A sentinel for unparseable tool-call input, aimed at being reported back to the calling LLM so it retries with valid JSON.

Solutions

1. Pass replacements as a proper JSON array, e.g. [{"old_str":"foo","new_str":"bar"}], not a malformed JSON string.
2. Validate the JSON with a parser or linter before sending it; unescaped quotes or trailing commas break JSON.parse.
3. If building the string in code, serialize the array with JSON.stringify instead of hand-writing it.

When it happens

Trigger: Thrown at packages/@n8n/ai-utilities/src/utils/text-editor.ts:178 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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

Appendix: source

Thrown at packages/@n8n/ai-utilities/src/utils/text-editor.ts:178

		.slice(startLine, endLine)
		.map((line, i) => `    ${startLine + i + 1}: ${line}`)
		.join('\n');

	return (
		`Closest match (${percentage}% of old_str matched, diverges at line ${divergeLine}):\n` +
		`  old_str: ...${escapeWhitespace(oldStrPrefix)}>>> ${escapeWhitespace(oldStrRemainder)}\n` +
		`  file:\n${fileContext}`
	);
}

export function parseStrReplacements(raw: unknown): StrReplacement[] {
	let parsed = raw;

	if (typeof parsed === 'string') {
		try {
			parsed = JSON.parse(parsed) as unknown;
		} catch {
			throw new Error(
				'replacements must be a JSON array of {old_str, new_str} objects, but received an invalid JSON string.',
			);
		}
	}

	if (!isUnknownArray(parsed)) {
		throw new Error(
			'replacements must be an array of {old_str, new_str} objects. Example: {"replacements": [{"old_str": "foo", "new_str": "bar"}]}',
		);
	}

	const replacements: StrReplacement[] = [];

	for (let i = 0; i < parsed.length; i++) {
		const item = parsed[i];
		if (!isObjectRecord(item) || typeof item.old_str !== 'string') {
			throw new Error(
				`replacements[${i}] is missing a valid "old_str" string. Each replacement must have {old_str: string, new_str: string}.`,

View on GitHub (pinned to 5ac6606e81)