n8n-io/n8n · error · Error

.${methodName}() must immediately follow adding a ${expected

Error message

.${methodName}() must immediately follow adding a ${expected} node. Use it as ${usage}.

What it means

The branching helpers onTrue()/onFalse()/onCase() must be called when the builder cursor is positioned on an IF (for onTrue/onFalse) or Switch (for onCase) node. The guard inspects the type of the node the cursor currently points to and rejects the call if it is not the expected branching type. The error message tells you exactly which node type is required and shows the correct chaining pattern.

Source

Thrown at packages/@n8n/workflow-sdk/src/workflow-builder.ts:429

	private branchFromCurrent(
		outputIndex: number,
		target: unknown,
		methodName: 'onTrue' | 'onFalse' | 'onCase',
	): WorkflowBuilder {
		const sourceKey = this._currentNode;
		const sourceType = sourceKey ? this._nodes.get(sourceKey)?.instance.type : undefined;
		const wantsSwitch = methodName === 'onCase';
		const matches = sourceType
			? wantsSwitch
				? isSwitchNodeType(sourceType)
				: isIfNodeType(sourceType)
			: false;
		if (!matches) {
			const expected = wantsSwitch ? 'Switch' : 'IF';
			const usage = wantsSwitch
				? 'workflow.add(trigger).to(switchNode).onCase(0, a).onCase(1, b)'
				: 'workflow.add(trigger).to(ifNode).onTrue(a).onFalse(b)';
			throw new Error(
				`.${methodName}() must immediately follow adding a ${expected} node. Use it as ${usage}.`,
			);
		}

		if (target === null || target === undefined) {
			this._currentNode = sourceKey;
			this._currentOutput = 0;
			return this;
		}

		this._currentNode = sourceKey;
		this._currentOutput = outputIndex;
		this.to(target as NodeInstance<string, string, unknown>);
		// Re-anchor the cursor on the branching node so the next sibling branch wires correctly.
		this._currentNode = sourceKey;
		this._currentOutput = 0;
		return this;
	}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Add the IF node and immediately call .onTrue(...)/.onFalse(...) on the same chain (the builder re-anchors the cursor on the branching node for sibling branches).
2. For Switch nodes, use .onCase(index, target) and ensure the source is a Switch node.
3. Verify the node type passed to isIfNodeType/isSwitchNodeType matches the method you are calling.

Example fix

// before
workflow.add(trigger({})).to(node({ type: 'Set' })).onTrue(a); // throws

// after
workflow.add(trigger({})).to(ifNode({ type: 'If' })).onTrue(a).onFalse(b);

import { isIfNodeType, isSwitchNodeType } from 'workflow-sdk';

const sourceType = wf.getCursorNodeType?.();
if (methodName === 'onCase' && !isSwitchNodeType(sourceType)) {
  throw new Error('Add a Switch node before calling onCase()');
}
if ((methodName === 'onTrue' || methodName === 'onFalse') && !isIfNodeType(sourceType)) {
  throw new Error('Add an IF node before calling onTrue()/onFalse()');
}

function isBranchingFor(method: 'onTrue'|'onFalse'|'onCase', nodeType: string): boolean {
  return method === 'onCase' ? isSwitchNodeType(nodeType) : isIfNodeType(nodeType);
}

try {
  wf.add(trigger({})).to(ifNode({ type: 'If' })).onTrue(a);
} catch (e) {
  if (e instanceof Error && /must immediately follow/.test(e.message)) {
    // cursor not on a branching node; restructure the chain
  }
  throw e;
}

When it happens

Trigger: Calling workflow.add(trigger({...})).to(regularNode).onTrue(a) — onTrue() runs but the cursor is on regularNode, not an IF node. Or calling onCase() after an IF node instead of a Switch node. Also triggered when the cursor has been advanced off the branching node by an intervening .to() that did not re-anchor.

Common situations: Forgetting to add the IF/Switch node before branching; chaining extra .to() calls between adding the IF and calling onTrue/onFalse so the cursor drifts; using onCase with an IF or onTrue with a Switch.

Related errors

• .onTrue() is only available on IF nodes (${NODE_TYPES.IF})
• .onFalse() is only available on IF nodes (${NODE_TYPES.IF})
• .onCase() is only available on Switch nodes (${NODE_TYPES.SW
• INVALID_CONNECTION
• VALIDATION_ERROR

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