mastra-ai/mastra · error · Error

Mapping references unknown workflow init-data "${source.init

Error message

Mapping references unknown workflow init-data "${source.initData}".

What it means

A mapping source of kind `initData` references a workflow by id whose init-data provides the mapped value. During rehydration, `rehydrateMapConfig` looks up that workflow via `mastra.getWorkflow(source.initData)`; if it is not registered, the mapping cannot be resolved and the library throws.

Source

Thrown at packages/core/src/workflows/dynamic/rehydrate.ts:333

 * step IDs because mapping execution resolves them from the run's step results.
 */
function rehydrateMapConfig(cfg: Record<string, any>, mastra: Mastra): Record<string, any> {
  const out: Record<string, any> = {};
  for (const [key, source] of Object.entries(cfg)) {
    if (!source || typeof source !== 'object') {
      out[key] = source;
      continue;
    }
    if ('template' in source) {
      out[key] = { template: source.template };
    } else if ('value' in source) {
      out[key] = { value: source.value };
    } else if ('requestContextPath' in source) {
      out[key] = { requestContextPath: source.requestContextPath };
    } else if ('initData' in source && typeof source.initData === 'string') {
      const wf = mastra.getWorkflow?.(source.initData);
      if (!wf) {
        throw new Error(`Mapping references unknown workflow init-data "${source.initData}".`);
      }
      out[key] = mapVariable({ initData: wf as any, path: source.path });
    } else if ('step' in source) {
      out[key] = mapVariable({ step: source.step as any, path: source.path });
    } else {
      out[key] = source;
    }
  }
  return out;
}

/**
 * Mastra.getAgentById throws when the id isn't registered; every by-id
 * resolution path in this file wants a nullable "does it exist?" answer so it
 * can fall through to a tool lookup or a targeted error. Swallow the not-found
 * throw and return undefined.
 */
function tryGetAgentById(mastra: Mastra, id: string): any | undefined {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the referenced workflow on the Mastra instance: `new Mastra({ workflows: { '<initData id>': wf } })`.
2. Fix the stored `initData` id if it was renamed or is mistyped.
3. Share workflow registration across services that rehydrate the same stored graphs.
4. Pre-validate every mapping source: assert `mastra.getWorkflow(source.initData)` exists before rehydrating.

Example fix

// before
const mastra = new Mastra({}); // mapping references initData 'sourceWf'

// after
const mastra = new Mastra({ workflows: { sourceWf } });

function assertInitDataWorkflowsRegistered(stored, mastra) {
  for (const e of stored.entries) {
    if (e.type === 'mapping') {
      for (const src of Object.values(e.config ?? {})) {
        if (src && typeof src === 'object' && 'initData' in src && !mastra.getWorkflow?.(src.initData)) {
          throw new Error(`initData workflow "${src.initData}" must be registered before rehydration`);
        }
      }
    }
  }
}

function initDataResolves(mastra: Mastra, source: unknown): boolean {
  const s = source as any;
  return !('initData' in (s ?? {})) || !!mastra.getWorkflow?.(s.initData);
}

try {
  const wf = rehydrateWorkflow(stored, mastra);
} catch (err) {
  const m = err instanceof Error && err.message.match(/unknown workflow init-data "([^"]+)"/);
  if (m) throw new Error(`Register workflow '${m[1]}' (init-data source) before rehydrating.`);
  throw err;
}

When it happens

Trigger: rehydrateWorkflow resolves a mapping config containing `{ initData: '<workflowId>' }` where no workflow with that id is registered on the current Mastra instance (typo, removed workflow, cross-environment registry mismatch).

Common situations: Renaming or deleting a workflow that other workflows' mappings depend on; deploying a stored workflow to a service missing the referenced workflow; copying graphs between projects.

Related errors

• Dynamic workflow references agent "${entry.agentId}" which i
• Dynamic workflow references tool "${entry.toolId}" which is
• Dynamic workflow references step "${id}" which is not regist
• mapping entries cannot appear inside .parallel(), .branch(),
• Dynamic workflow references nested workflow "${workflowId}"

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