mastra-ai/mastra · error · Error

Stored mapping step "${stepId}" has invalid JSON mapConfig:

Error message

Stored mapping step "${stepId}" has invalid JSON mapConfig: ${(e as Error).message}

What it means

Dynamic mapping steps persist their configuration as a JSON string in mapConfig. parseMapConfig JSON.parses that string and, if it is malformed, throws an error that names the offending step id and includes the underlying JSON.parse message, so stored workflows fail loudly instead of silently mis-mapping data.

Source

Thrown at packages/core/src/workflows/dynamic/mapping-config.ts:26

 *   collects issues, and infers the mapping's output schema in the same pass
 *   (the two are inseparable — a descriptor's validity determines its
 *   contribution to the output shape).
 *
 * Template syntax checking delegates to `mapping-template.ts`'s
 * `validateTemplate` — the same parser the runtime uses — plus a scope check
 * over the placeholders' step ids.
 */
import { collectTemplateStepIds, validateTemplate } from '../mapping-template';
import type { JsonSchema } from './json-schema-to-zod';
import { isCanonicalMappingPath, isRecord, schemaAtPath, schemaForValue } from './validate/schema-utils';
import type { WorkflowValidationIssue } from './validate/types';

/** Parses a stored mapConfig JSON string; throws with the step id on malformed JSON. */
export function parseMapConfig(raw: string, stepId: string): Record<string, any> {
  try {
    return JSON.parse(raw) as Record<string, any>;
  } catch (e) {
    throw new Error(`Stored mapping step "${stepId}" has invalid JSON mapConfig: ${(e as Error).message}`);
  }
}

/** A recognizable Handlebars/Mustache placeholder: `{{ name }}`, `{{a.b}}`, … */
const HANDLEBARS_PLACEHOLDER = /\{\{\s*[\w$][\w.$-]*\s*\}\}/;

export interface MapConfigAnalysisOptions {
  /** Issue path prefix of the mapping entry, e.g. `graph.2`. */
  path: string;
  /** Outputs of preceding workflow-local steps (schema may be undefined when unknown). */
  availableOutputs: ReadonlyMap<string, JsonSchema | undefined>;
  /** The workflow's input schema (for `{ initData: true }` sources). */
  inputSchema: JsonSchema | undefined;
  /** The workflow's request-context schema (for `{ requestContextPath }` sources). */
  requestContextSchema: JsonSchema | undefined;
}

export interface MapConfigAnalysis {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the mapConfig column for the named step id and fix/rewrite it as valid JSON.
2. Re-save the mapping step via the builder/API so a correct mapConfig is persisted.
3. Restore the row from a backup if the config was corrupted in storage.

Example fix

// before (stored mapConfig)
{"items": "{{inputs.a",   // truncated
// after
{"items": "{{inputs.a}}"}

function assertValidMapConfig(raw, stepId) {
  try { JSON.parse(raw); } catch (e) {
    throw new Error(`mapConfig for step "${stepId}" is not valid JSON`);
  }
}

try {
  const cfg = parseMapConfig(raw, stepId);
} catch (e) {
  if (e instanceof Error && e.message.includes('invalid JSON mapConfig')) {
    // rebuild mapConfig via the builder API or restore the row from backup
  }
  throw e;
}

When it happens

Trigger: Rehydrating a workflow from storage whose mapping step row contains corrupted/truncated mapConfig JSON — e.g. manual DB edits, a failed write, escaping bugs when the config was saved, or an older serialization format being read by new code.

Common situations: Database migrations or hand-edited rows corrupting the JSON; application bug that stored a non-JSON string (e.g. a template string with unescaped quotes); restore from backup with partially written rows.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse A2A stream event: ${error instanceof Error ?
• Linear cursor is invalid.
• Rule metadata must contain finite numbers.
• Rule metadata is not bounded JSON.
• Rule metadata must not contain cycles.

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