mastra-ai/mastra · error · Error

Dynamic workflow bundle contains more than one definition wi

Error message

Dynamic workflow bundle contains more than one definition with id "${def.id}". Ids must be unique within a bundle.

What it means

When loading a dynamic workflow bundle, Mastra validates that every definition id in the bundle is unique by inserting ids into a Set and throwing a plain Error on the first duplicate. Duplicate ids would make member lookup and nested-workflow resolution ambiguous, so they are rejected up front.

Source

Thrown at packages/core/src/mastra/index.ts:4974

   * `addDynamicWorkflow()` is the single-member case.
   *
   * @example
   * ```typescript
   * await mastra.addDynamicWorkflows([
   *   { id: 'lookup-first-customer', ... },  // helper — order is derived, not assumed
   *   { id: 'parallel-customer-lookup', ... }, // root, nests the helper above
   * ]);
   * ```
   */
  public async addDynamicWorkflows(
    defs: readonly (DynamicWorkflowGraph | WorkflowBuilderDefinitionInput)[],
  ): Promise<void> {
    if (defs.length === 0) return;

    const seen = new Set<string>();
    for (const def of defs) {
      if (seen.has(def.id)) {
        throw new Error(
          `Dynamic workflow bundle contains more than one definition with id "${def.id}". Ids must be unique within a bundle.`,
        );
      }
      seen.add(def.id);
    }

    // Save-path is strict (boot-time load is lenient — see #loadDynamicWorkflows).
    // Normalization coerces the wire shape; one validation call per member
    // covers structure, JSON-Schema keywords, references, and schema-flow.
    const members = defs.map(def => ({
      normalized: normalizeWorkflowBuilderDefinition({
        id: def.id,
        description: def.description,
        metadata: def.metadata,
        inputSchema: def.inputSchema,
        outputSchema: def.outputSchema,
        stateSchema: def.stateSchema,
        requestContextSchema: def.requestContextSchema,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Find the definitions sharing the id (the message names it) and give each a unique workflow id at creation.
2. Deduplicate the defs array before passing it (filter by id, keeping one occurrence).
3. Rename the copied workflow's id parameter so variants get distinct ids.
4. Fix the file/glob gathering logic so a single workflow is not included twice.

Example fix

// before
const defs = [makeWorkflow({ id: 'deploy' }), makeWorkflow({ id: 'deploy' })];
await registerDynamicWorkflowBundle(defs);
// after
const defs = [makeWorkflow({ id: 'deploy-staging' }), makeWorkflow({ id: 'deploy-prod' })];
await registerDynamicWorkflowBundle(defs);

const ids = defs.map(d => d.id);
const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
if (dupes.length > 0) {
  throw new Error(`Duplicate workflow ids in bundle: ${[...new Set(dupes)].join(', ')}`);
}

try {
  await registerDynamicWorkflowBundle(defs);
} catch (e) {
  if (e instanceof Error && /more than one definition with id/.test(e.message)) {
    console.error('Deduplicate defs before registering:', e.message);
  } else throw e;
}

When it happens

Trigger: Calling the dynamic workflow bundle loader with a defs array containing two or more definitions whose def.id is the same string — e.g. the same workflow object included twice, or two factories emitting workflows with the same id.

Common situations: Globbing workflow files where two files export workflows with a shared id; concatenating bundles from multiple sources without deduplication; forgetting to version/rename a workflow id when copying one to create a variant.

Related errors

• @mastra/livekit: `workflowInput` is required when `workflow`
• Dynamic workflow bundle has a circular nested-workflow depen
• SCHEDULES_INVALID_WORKFLOW_PATCH
• ${path} must contain only plain objects.
• Workflow definition graph must be an array.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/77e52ef825ca6b25. Report an issue: GitHub.