mastra-ai/mastra · error · Error

${label} references unknown namespace "${scope}". Use one of

Error message

${label} references unknown namespace "${scope}". Use one of: ${TEMPLATE_NAMESPACES.join(', ')}.

What it means

Thrown by resolveTemplatePlaceholder when a mapping template placeholder references a namespace scope that is not one of the known TEMPLATE_NAMESPACES. validateTemplate normally rejects malformed templates, so this is a safety net for templates constructed programmatically and injected into stepFlow without validation.

Source

Thrown at packages/core/src/workflows/mapping-template.ts:182

      const subPath = innerDot === -1 ? '' : rest.slice(innerDot + 1);
      const stepResult = ctx.getStepResult(stepId);
      // Nullish (not just null) so a step that "succeeded" with `undefined`
      // output is reported as missing too — consistent with how predicates
      // treat nullish step results. Nullish *path values inside* a present
      // result still render as '' via stringifyTemplateValue.
      if (stepResult == null) {
        throw new Error(
          `${label} references stepResults.${stepId} but step "${stepId}" has no successful output ` +
            `(not run yet, not registered, failed, or produced no output).`,
        );
      }
      return stringifyTemplateValue(traverseMappingPath(stepResult, subPath, label), template, idx, rawExpr);
    }
    default:
      // validateTemplate guarantees this branch is unreachable for well-formed
      // workflows; this is a safety net for templates that bypassed validation
      // (e.g. constructed programmatically and pushed into stepFlow).
      throw new Error(
        `${label} references unknown namespace "${scope}". Use one of: ${TEMPLATE_NAMESPACES.join(', ')}.`,
      );
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the placeholder namespace prefix against the list printed in the error (TEMPLATE_NAMESPACES.join(', ')) and correct it.
2. Fix the typo in the template string (e.g. 'step' vs 'steps').
3. Ensure any programmatically built templates pass through validateTemplate before entering stepFlow.
4. Log the full template string at construction time to catch malformed scopes early.

Example fix

// before
const tmpl = '{{stepsData.stepOne.output}}';
// after
const tmpl = '{{steps.stepOne.output}}';

const KNOWN = ['steps','trigger',' inputData','context']; // TEMPLATE_NAMESPACES
function validateNs(t: string) { const m = t.match(/\{\{(\w+)\./); if (!m || !KNOWN.includes(m[1])) throw new Error(`Unknown template namespace in: ${t}`); }

try {
  resolveTemplate(tpl, ctx);
} catch (e) {
  if ((e as Error).message.includes('references unknown namespace')) {
    console.error('Fix template namespace:', tpl);
  } else throw e;
}

When it happens

Trigger: Calling resolveTemplate (which calls resolveTemplatePlaceholder) with a template whose placeholder uses an unrecognized prefix, e.g. '{{foo.stepId.output}}' instead of a known namespace like '{{'steps.'...}}'. Typically only reachable by constructing template objects programmatically and pushing them into stepFlow, bypassing validateTemplate.

Common situations: Hand-written or generated mapping templates with typos in the namespace prefix; templates copied from older docs or another library's syntax; programmatic template generation that emits an invalid scope.

Related errors

• @mastra/livekit: no workflow specified. Set `workflow` on cr
• create-workflow requires a Mastra context.
• The "workflow-builder" sub-agent is not registered on this M
• create-workflow failed: save-workflow threw ${saveErrors.len
• create-workflow failed: the workflow-builder sub-agent never

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