mastra-ai/mastra · error · Error

Unknown stored step type: ${JSON.stringify(_exhaustive)}

Error message

Unknown stored step type: ${JSON.stringify(_exhaustive)}

What it means

applyGraphEntry uses a TypeScript exhaustive switch over the stored entry `type` discriminant. Reaching the `default` branch means the entry's type is not one of the known stored step types, which should be impossible for correctly typed data — so the `never` assignment is a compile-time exhaustiveness guard and the throw is a runtime backstop against corrupt or newer-format stored graphs.

Source

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

      const step = rehydrateSingleEntry(entry.step, mastra, schemaOpts);
      const serializedCondition = entry.serializedCondition ?? {
        id: `${getSingleStepEntryId(step)}-condition`,
        fn: derivePredicateLabel(predicate),
      };
      const live: StepFlowEntry = {
        type: 'loop',
        step,
        condition: predicateToCondition(predicate),
        loopType,
        serializedCondition,
        predicate,
      };
      wf.__pushStepFlowEntry(live, { ...entry, serializedCondition });
      return;
    }
    default: {
      const _exhaustive: never = entry;
      throw new Error(`Unknown stored step type: ${JSON.stringify(_exhaustive)}`);
    }
  }
}

/**
 * Reconstruct the options bag `.agent()` accepts from a serialized entry.
 * Restores `structuredOutput.schema` from `outputSchema` (JSON Schema → Zod)
 * and merges in `retries` / `metadata`. Returns `undefined` when nothing to
 * restore so `.agent(agentId)` stays a clean call.
 */
function rebuildAgentOptions(
  entry: {
    outputSchema?: Record<string, any>;
    options?: SerializedStepOptions;
  },
  schemaOpts?: JsonSchemaToZodOptions,
): Record<string, any> | undefined {
  const opts: Record<string, any> = {};

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra/core to the same (or newer) version that wrote the stored graph so the entry type is recognized.
2. Inspect the stored graph JSON and find the offending entry's `type` value; fix or remove it.
3. Validate stored graph JSON against the expected schema before calling rehydrateWorkflow.
4. Re-serialize the workflow from its source definition using the current runtime version.

Example fix

// before: loading v-next stored data on older runtime
const entry = stored.entries[3]; // type: 'wait-event' (unknown here)

// after: upgrade core, or guard
if (!isKnownStoredEntryType(entry.type)) throw new Error('Incompatible stored workflow version; upgrade @mastra/core');

const KNOWN_TYPES = new Set(['step', 'agent', 'tool', 'mapping', 'sleep', 'sleepUntil', 'conditional', 'loop', 'parallel', 'branch', 'foreach', 'waitUntil', 'sleepEvent']);
function validateStoredTypes(graph) {
  for (const e of graph.entries) {
    if (!KNOWN_TYPES.has(e.type)) throw new Error(`Incompatible stored entry type: ${e.type}`);
  }
}

function isKnownStoredEntry(type: string): boolean {
  return ['step','agent','tool','mapping','sleep','sleepUntil','conditional','loop','parallel','branch','foreach'].includes(type);
}

try {
  const wf = rehydrateWorkflow(stored, mastra);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown stored step type')) {
    throw new Error('Stored workflow was written by a newer/other version; upgrade @mastra/core and retry.');
  }
  throw err;
}

When it happens

Trigger: rehydrateWorkflow processes a stored graph JSON containing an entry whose `type` value is unrecognized — e.g. data produced by a newer library version with new entry types, a corrupted/hand-edited stored graph, or unvalidated JSON from external storage cast to the entry type.

Common situations: Loading workflows stored by a newer mastra/core version into an older runtime; manual edits or migrations that introduced an invalid `type`; storage backends holding arbitrary JSON that was never validated against the stored-entry schema.

Related errors

• Cannot rehydrate conditional step: missing or mismatched pre
• Cannot rehydrate loop step: missing declarative predicate or
• Sleep step "${entry.id}" cannot be stored: dynamic duration
• Unknown step entry type: ${JSON.stringify(_exhaustive)}
• ${describeBadPlaceholder(template, idx, rawExpr)} resolved t

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