It is not possible to have actors with the same id, even if

Error message

It is not possible to have actors with the same id, even if one is destroyed before the next is created. Use 'AS' aliases to simulate the behavior

What it means

On the `createParticipant` message command, if the actor id already exists in the actors map, mermaid throws even if the actor was previously destroyed. Ids are immutable identities for the whole diagram; destroy only hides the lifeline, it does not free the id. The message suggests `AS` aliases as the supported workaround.

Source

Thrown at packages/mermaid/src/diagrams/sequence/sequenceDb.ts:583

          this.state.records.messages.push({
            id: this.state.records.messages.length.toString(),
            from: undefined,
            to: undefined,
            message: {
              start: param.sequenceIndex,
              step: param.sequenceIndexStep,
              visible: param.sequenceVisible,
            },
            wrap: false,
            type: param.signalType,
          });
          break;
        case 'addParticipant':
          this.addActor(param.actor, param.actor, param.description, param.draw, param.config);
          break;
        case 'createParticipant':
          if (this.state.records.actors.has(param.actor)) {
            throw new Error(
              "It is not possible to have actors with the same id, even if one is destroyed before the next is created. Use 'AS' aliases to simulate the behavior"
            );
          }
          this.state.records.lastCreated = param.actor;
          this.addActor(param.actor, param.actor, param.description, param.draw, param.config);
          this.state.records.createdActors.set(param.actor, this.state.records.messages.length);
          break;
        case 'destroyParticipant':
          this.state.records.lastDestroyed = param.actor;
          this.state.records.destroyedActors.set(param.actor, this.state.records.messages.length);
          break;
        case 'activeStart':
          this.addSignal(param.actor, undefined, undefined, param.signalType);
          break;
        case 'centralConnection':
          this.addSignal(param.actor, undefined, undefined, param.signalType);
          break;
        case 'centralConnectionReverse':

View on GitHub (pinned to d93e9c88c0)

Solutions

Use a distinct id with `AS`, e.g. `create ParticipantX2 as ParticipantX`.
Remove the earlier declaration/creation of that id if you truly want a fresh participant.
Avoid `create` for an actor that already exists; just send a message to it.
If recreating, alias each incarnation separately so each id is unique.

Example fix

// before
participant Alice
create Alice   // id reuse -> throws

// after — alias the new incarnation
participant Alice
create Alice2 as Alice

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the id is unused before emitting `create`
if (actors.has(id)) {
  throw new Error(`Cannot create '${id}': id already exists; use an AS alias`);
}

Type guard

const isCreateDuplicateError = (e): boolean =>
  e instanceof Error && /actors with the same id/.test(e.message);

Try / catch

try {
  await mermaid.run({ nodes: [el] });
} catch (e) {
  if (e instanceof Error && /actors with the same id/.test(e.message)) {
    // suggest an AS alias for the recreation
  } else { throw e; }
}

Prevention

Treat actor ids as unique for the whole diagram, even after destroy.
Use `AS` to alias recreated incarnations.
Avoid `create` for already-declared participants.

When it happens

Trigger: Using `create ParticipantX` when `ParticipantX` was already declared or created earlier in the diagram, regardless of an intervening `destroy ParticipantX`.

Common situations: Modeling a resource that is created/destroyed/recreated and reusing the same name; renaming a participant but forgetting the original still exists; generated diagrams that emit `create` on every loop iteration.

Related errors

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