Architecture layout failed: a declared `align row|column` di

Error message

Architecture layout failed: a declared `align row|column` directive likely contradicts the edge directions, or two declared alignments overlap on a shared node. Check that the order of members in each `align` chain is consistent with the edges between them, and that no node appears in two `align` directives along the same axis.

What it means

Thrown by the architecture renderer when the fcose layout engine raises a RangeError with the message 'Invalid array length' during layout.run(). fcose raises this from FDLayout.calcGrid when the alignment constraints it receives are unsatisfiable. The renderer catches the raw RangeError and rethrows with actionable context. This is a render-time error, not a parse-time one — the DB accepted the diagram, but the layout math has no solution.

Source

Thrown at packages/mermaid/src/diagrams/architecture/architectureRenderer.ts:592

            edge.style('segment-distances', distances);
            edge.style('segment-weights', weights);
          }
        }
      }
      cy.endBatch();
      withSeededRandom(seed, () => layout.run());
    });
    try {
      withSeededRandom(seed, () => layout.run());
    } catch (err) {
      // fcose throws a raw `RangeError: Invalid array length` from inside
      // FDLayout.calcGrid when the constraints it receives are unsatisfiable
      // (e.g. an `align row|column` chain whose member order contradicts the
      // edge directions, or two declared alignments that overlap on a node).
      // Rethrow with actionable context so users don't have to chase the
      // failure into fcose internals.
      if (err instanceof RangeError && err.message.includes('Invalid array length')) {
        throw new Error(
          'Architecture layout failed: a declared `align row|column` directive ' +
            'likely contradicts the edge directions, or two declared alignments ' +
            'overlap on a shared node. Check that the order of members in each ' +
            '`align` chain is consistent with the edges between them, and that ' +
            'no node appears in two `align` directives along the same axis.'
        );
      }
      throw err;
    }

    cy.ready((e) => {
      log.info('Ready', e);
      resolve(cy);
    });
  });
}

export const draw: DrawDefinition = async (text, id, _version, diagObj: Diagram) => {

View on GitHub (pinned to d93e9c88c0)

Solutions

Reorder each align chain's members so the order is consistent with the edge directions between them.
Ensure no node appears in two `align` directives on the same axis (two rows or two columns).
Temporarily remove align directives one at a time to isolate which constraint contradicts the edges.
If the conflict is unintended, flip the direction of the offending edge(s) to match the desired alignment.

Example fix

// before — edge says b is right of a, but align says a is right of b
architecture-beta
  service a
  service b
  a:R -- b:L
  align row: b, a
// after — make the align order match the edge-implied order
architecture-beta
  service a
  service b
  a:R -- b:L
  align row: a, b

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await mermaid.render(id, diagramText);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Architecture layout failed')) {
    // Strip or reorder conflicting `align` directives, then retry.
    console.warn('Layout constraint conflict:', err.message);
  }
  throw err;
}

Prevention

Keep align member order consistent with the edge-implied spatial order.
Never list the same node in two align directives on the same axis.
When adding a new align directive, mentally verify it does not contradict existing edges.

When it happens

Trigger: An `align row` or `align column` chain whose member order contradicts the directions implied by edges between those members (e.g. align says A is left of B but an edge forces A right of B). Also: the same node appearing in two align directives along the same axis, which over-constrains the system.

Common situations: Complex diagrams mixing many edges with several align directives; iterative editing where an align directive is added without re-checking edge directions; align chains copied from another diagram whose edges run the opposite way.

Related errors

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