mermaid-js/mermaid · error

Columns must be an integer !== 0.

Error message

Columns must be an integer !== 0.

What it means

Thrown by calculateBlockPosition in the block diagram layout when `columns` is 0 or not an integer. Negative integers are explicitly allowed (they mean 'auto columns'). The function computes a grid position from (columns, position), so a zero column count would divide by zero and a non-integer has no grid meaning.

Source

Thrown at packages/mermaid/src/diagrams/block/layout.ts:15

import type { BlockDB } from './blockDB.js';
import type { Block } from './blockTypes.js';
import { log } from '../../logger.js';
import { getConfig } from '../../diagram-api/diagramAPI.js';

interface BlockPosition {
  px: number;
  py: number;
}

export function calculateBlockPosition(columns: number, position: number): BlockPosition {
  // log.debug('calculateBlockPosition abc89', columns, position);
  // Ensure that columns is a positive integer
  if (columns === 0 || !Number.isInteger(columns)) {
    throw new Error('Columns must be an integer !== 0.');
  }

  // Ensure that position is a non-negative integer
  if (position < 0 || !Number.isInteger(position)) {
    throw new Error('Position must be a non-negative integer.' + position);
  }

  if (columns < 0) {
    // Auto columns is set
    return { px: position, py: 0 };
  }
  if (columns === 1) {
    // Auto columns is set
    return { px: 0, py: position };
  }
  // Calculate posX and posY
  const px = position % columns;
  const py = Math.floor(position / columns);

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Set columns to a positive integer (>=1) for a fixed grid, or a negative integer (typically -1) for auto layout.
2. Ensure the value is an integer — round or floor any computed column count before passing it in.

Example fix

// before
calculateBlockPosition(0, 3);
calculateBlockPosition(2.5, 3);
// after
calculateBlockPosition(2, 3);   // fixed 2-column grid
calculateBlockPosition(-1, 3);  // auto columns

function calculateBlockPositionSafe(columns, position) {
  if (columns === 0 || !Number.isInteger(columns)) {
    throw new Error(`columns must be a non-zero integer; got ${columns}`);
  }
  return calculateBlockPosition(columns, position);
}

const isValidColumns = (c) => Number.isInteger(c) && c !== 0;

When it happens

Trigger: Calling calculateBlockPosition(0, pos) or calculateBlockPosition(2.5, pos). Internally this is driven by block.columns, which defaults to -1 (auto); a value of 0 typically comes from misconfiguration or an uninitialized field.

Common situations: A block whose `columns` property is left at 0 or set to a fractional value; computed column counts that round incorrectly; default values from partial config objects.

Related errors

• Position must be a non-negative integer.${position}
• No nodes found in layout data
• Layout data is required
• Configuration is required in layout data
• Nodes array is required in layout data

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