n8n-io/n8n · error · NodeNotFoundError

NODE_NOT_FOUND

NODE_NOT_FOUND

Error message

Node with ID "${nodeId}" not found in workflow

What it means

Factory createNodeNotFoundError in helpers/validation.ts wraps a NodeNotFoundError instance. It is returned (not thrown) by helpers that resolve a node by identifier (ID or name) and find no match in workflow.nodes. Consumers report it via reporter.error and createErrorResponse.

Source

Thrown at packages/@n8n/ai-workflow-builder.ee/src/tools/helpers/validation.ts:100

	details?: Record<string, string>,
): ToolError {
	// Create the appropriate error instance for better tracking
	const error = new ValidationError(message, { tags: { code, ...details } });
	return {
		message: error.message,
		code,
		details,
	};
}

/**
 * Create a node not found error
 */
export function createNodeNotFoundError(nodeIdentifier: string): ToolError {
	const error = new NodeNotFoundError(nodeIdentifier);
	return {
		message: error.message,
		code: 'NODE_NOT_FOUND',
		details: { nodeIdentifier },
	};
}

/**
 * Create a node type not found error
 */
export function createNodeTypeNotFoundError(nodeTypeName: string): ToolError {
	const error = new NodeTypeNotFoundError(nodeTypeName);
	return {
		message: error.message,
		code: 'NODE_TYPE_NOT_FOUND',
		details: { nodeTypeName },
	};
}

/**
 * Create a node parameter is too large error

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Call list_nodes to get the current set of IDs and names.
2. Pass a currently-valid ID (preferred) or exact name.
3. If the node was renamed, use the new name or re-resolve by ID.

import { findNodeByIdOrName } from '@/tools/helpers/validation';

// Resolve before invoking the consuming tool.
const node = findNodeByIdOrName(identifier, workflow.nodes);
if (!node) { /* surface 'unknown identifier' to the agent, call list_nodes */ }

function isToolError(v: unknown): v is { message: string; code: string; details?: unknown } {
  return typeof v === 'object' && v !== null && 'code' in v && 'message' in v;
}

// NODE_NOT_FOUND is returned in the structured ToolError shape, not thrown.
const res = await someTool.invoke(input);
if (isToolError(res) && res.code === 'NODE_NOT_FOUND') {
  const id = (res.details as any).nodeIdentifier;
  // refresh node list and re-resolve
}

When it happens

Trigger: Any tool that calls validateNodeExists / findNodeByIdOrName and the identifier matches neither an ID nor a (case-insensitive) name.

Common situations: Stale node ID cached from a prior session; the node was renamed or deleted; typo in a name; wrong workflow loaded.

Related errors

• NODES_NOT_FOUND
• SAME_NAME
• NAME_CONFLICT
• INVALID_CONNECTION
• VALIDATION_ERROR

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