mermaid-js/mermaid · error · Error

No such shape: ${doc.shape}. Shape names should be lowercase

Error message

No such shape: ${doc.shape}. Shape names should be lowercase.

What it means

Thrown by setMetadata when YAML metadata attached to a kanban item declares a shape field that is either not fully lowercase or contains an underscore. The guard rejects shapes that don't match the expected lowercase convention before they reach the shape-lookup logic, because kanban only supports a fixed set of shape names and a mismatched case or underscore would silently fail to match.

Source

Thrown at packages/mermaid/src/diagrams/kanban/kanbanDb.ts:132

    padding,
    isGroup: false,
  } satisfies KanbanNode;

  if (shapeData !== undefined) {
    let yamlData;
    // detect if shapeData contains a newline character
    // console.log('shapeData', shapeData);
    if (!shapeData.includes('\n')) {
      // console.log('yamlData shapeData has no new lines', shapeData);
      yamlData = '{\n' + shapeData + '\n}';
    } else {
      // console.log('yamlData shapeData has new lines', shapeData);
      yamlData = shapeData + '\n';
    }
    const doc = yaml.load(yamlData, { schema: yaml.JSON_SCHEMA }) as NodeMetaData;
    // console.log('yamlData', doc);
    if (doc.shape && (doc.shape !== doc.shape.toLowerCase() || doc.shape.includes('_'))) {
      throw new Error(`No such shape: ${doc.shape}. Shape names should be lowercase.`);
    }

    // if shape is defined in the yaml data, use it if it is a valid shape kanbanItem
    if (doc?.shape && doc.shape === 'kanbanItem') {
      node.shape = doc?.shape;
    }
    if (doc?.label) {
      node.label = doc?.label;
    }
    if (doc?.icon) {
      node.icon = doc?.icon.toString();
    }
    if (doc?.assigned) {
      node.assigned = doc?.assigned.toString();
    }
    if (doc?.ticket) {
      node.ticket = doc?.ticket.toString();
    }

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Use the exact lowercase shape name with no underscores: the only currently accepted kanban shape is 'kanbanItem' — wait, note the check rejects underscores, so verify against the latest docs which shape tokens are valid.
2. Re-read the kanban metadata docs for the supported shape vocabulary and use the exact token.
3. Remove the shape field entirely to fall back to the default kanban item shape.
4. Validate your YAML with a linter before feeding it to mermaid.

Example fix

// before
item @{{ shape: Kanban_Item }}

// after — omit shape or use the documented lowercase token
item @{{ shape: kanbanItem }}

// Normalize/validate shape metadata before rendering.
function normalizeShape(meta: { shape?: string }): string | null {
  if (!meta.shape) return null;
  if (meta.shape !== meta.shape.toLowerCase() || meta.shape.includes('_')) {
    return `Shape '${meta.shape}' must be lowercase with no underscores`;
  }
  return null;
}

function isValidShapeName(shape: string): boolean {
  return shape === shape.toLowerCase() && !shape.includes('_');
}

try {
  await mermaid.render('g', diagramText);
} catch (e) {
  if (e instanceof Error && /No such shape/.test(e.message)) {
    showUserError('Shape names in kanban metadata must be lowercase with no underscores. Check the shape field in your item metadata.');
  } else {
    throw e;
  }
}

When it happens

Trigger: Writing inline YAML metadata on a kanban item like {shape: KanbanItem} or {shape: kanban_item} — uppercase letters or underscores trip the check; also any custom shape value that doesn't follow lowercase-no-underscore naming.

Common situations: Copy-pasting shape names from docs that use TitleCase in prose; assuming underscore_separated names work because other diagrams use them; hand-writing JSON/YAML metadata blocks without normalizing case.

Related errors

• Items without section detected, found section ("${nodes[i].l
• Packet block ${start} - ${end} is invalid. End must be great
• Packet block ${start} - ${end ?? start} is not contiguous. I
• Packet block ${start} is invalid. Cannot have a zero bit fie
• "${label}" has invalid value: ${value}. Negative values are

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