mermaid-js/mermaid · error

Nodes array is required in layout data

Error message

Nodes array is required in layout data

What it means

Thrown by validateLayoutData when data.nodes is present but not an array. Unlike executeTidyTreeLayout's guard, this fires for type mismatches (object, string, number) even when the value is truthy, so it catches malformed shapes that an empty-length check alone would miss.

Source

Thrown at packages/mermaid-layout-tidy-tree/src/layout.ts:645

  });
}

/**
 * Validate layout data structure
 * @param data - The data to validate
 * @returns True if data is valid, throws error otherwise
 */
export function validateLayoutData(data: LayoutData): boolean {
  if (!data) {
    throw new Error('Layout data is required');
  }

  if (!data.config) {
    throw new Error('Configuration is required in layout data');
  }

  if (!Array.isArray(data.nodes)) {
    throw new Error('Nodes array is required in layout data');
  }

  if (!Array.isArray(data.edges)) {
    throw new Error('Edges array is required in layout data');
  }

  return true;
}

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Ensure data.nodes is always an Array<Node>; convert with Array.from(...) or Object.values(...) at the producer.
2. Run JSON.parse before validation if the payload came over a transport.
3. Add a TypeScript type annotation (nodes: Node[]) so the mismatch is caught at compile time.

Example fix

// before
validateLayoutData({ nodes: nodesMap, edges, config }); // Map

// after
validateLayoutData({ nodes: [...nodesMap.values()], edges, config });

if (!Array.isArray(data.nodes)) {
  data.nodes = Object.values(data.nodes ?? {});
}
validateLayoutData(data);

function hasNodeArray(data: unknown): data is { nodes: unknown[] } {
  return Array.isArray((data as any).nodes);
}

When it happens

Trigger: Passing data.nodes as a Map, an object keyed by id, a single node object, or a serialized JSON string that was never parsed.

Common situations: A producer stored nodes in a record/object and forwarded it directly, or a JSON.parse boundary was skipped so nodes arrived as a string.

Related errors

• No nodes found in layout data
• Edges array is required in layout data
• No nodes available to create tree
• Layout data is required
• Configuration is required in layout data

AI-assisted analysis of mermaid-js/mermaid@d93e9c88c0 (2026-08-12). Data as JSON: /api/errors/a6cd8bbaae2d9718. Report an issue: GitHub.