mermaid-js/mermaid · error

align ${hint.direction} references [${id}], which is not a s

Error message

align ${hint.direction} references [${id}], which is not a service or junction

What it means

Thrown by ArchitectureDB.addLayoutHint when a member id is not registered as a 'node' (i.e. not a service or junction). The registeredIds map must contain the id with value 'node'; groups (registered as 'group') and unknown ids both fail this check. Align directives operate on services and junctions only — groups cannot be aligned.

Source

Thrown at packages/mermaid/src/diagrams/architecture/architectureDb.ts:272

      lhsNode.edges.push(this.edges[this.edges.length - 1]);
      rhsNode.edges.push(this.edges[this.edges.length - 1]);
    }
  }

  public getEdges(): ArchitectureEdge[] {
    return this.edges;
  }

  public addLayoutHint(hint: ArchitectureLayoutHint): void {
    if (hint.members.length < 2) {
      throw new Error(
        `An align directive requires at least two members; got ${hint.members.length}`
      );
    }
    const seen = new Set<string>();
    hint.members.forEach((id) => {
      if (this.registeredIds.get(id) !== 'node') {
        throw new Error(
          `align ${hint.direction} references [${id}], which is not a service or junction`
        );
      }
      if (seen.has(id)) {
        throw new Error(`align ${hint.direction} lists [${id}] more than once`);
      }
      seen.add(id);
    });
    this.layoutHints.push(hint);
  }

  public getLayoutHints(): ArchitectureLayoutHint[] {
    return this.layoutHints;
  }

  /**
   * Returns the current diagram's adjacency list, spatial map, & group alignments.
   * If they have not been created, run the algorithms to generate them.

View on GitHub (pinned to d93e9c88c0)

Solutions

1. Reference only ids declared via addService or addJunction.
2. Verify every member id is spelled correctly and was declared before addLayoutHint is called.

Example fix

// before
db.addGroup({ id: 'grp' });
db.addService({ id: 'svc' });
db.addLayoutHint({ direction: 'row', members: ['grp', 'svc'] }); // 'grp' is a group
// after
db.addService({ id: 'svc2' });
db.addLayoutHint({ direction: 'row', members: ['svc', 'svc2'] });

function addLayoutHintSafe(db, hint) {
  for (const id of hint.members) {
    const node = db.getNode(id);
    if (!node) {
      throw new Error(`align member '${id}' is not a declared service/junction`);
    }
  }
  db.addLayoutHint(hint);
}

const isAlignableNode = (db, id) => db.getNode(id) !== null;

When it happens

Trigger: Calling db.addLayoutHint({ direction: 'row', members: ['groupA', 'svc1'] }) where 'groupA' is a group; or members: ['unknown'] where the id was never declared.

Common situations: Referencing a group id in an align directive by mistake; typo in a member id; referencing a junction before it is declared.

Related errors

• An align directive requires at least two members; got ${hint
• align ${hint.direction} lists [${id}] more than once
• Nodes array is required in layout data
• Edges array is required in layout data
• The group [${id}]'s parent is not a group

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