mastra-ai/mastra · error

Invalid signal type: ${input.type}. Use a supported signal t

Error message

Invalid signal type: ${input.type}. Use a supported signal type and set tagName for custom XML tags.

What it means

Agent signals (system-reminder style injections) support a limited set of `type` values, e.g. 'reactive' and 'state' plus a custom-XML-tag type. normalizeSignalType validates the input type before building the signal; an unrecognized type string throws this error. Custom tags must supply a `tagName` since the type alone doesn't map to one.

Source

Thrown at packages/core/src/agent/signals.ts:202

  tagName: AgentSignalTagName;
} {
  if (input.type === 'user-message') {
    return { type: 'user', tagName: input.tagName ?? 'user' };
  }

  if (input.type === 'system-reminder') {
    return { type: 'reactive', tagName: input.tagName ?? 'system-reminder' };
  }

  if (input.type === 'user' || input.type === 'state' || input.type === 'notification') {
    return { type: input.type, tagName: input.tagName ?? input.type };
  }

  if (input.type === 'reactive') {
    return { type: 'reactive', tagName: input.tagName ?? 'system-reminder' };
  }

  throw new Error(
    `Invalid signal type: ${input.type}. Use a supported signal type and set tagName for custom XML tags.`,
  );
}

function normalizeSignal(signal: AgentSignalInput | CreatedAgentSignal) {
  const { type, tagName } = normalizeSignalType(signal);
  return {
    ...signal,
    type,
    tagName,
    id: signal.id ?? crypto.randomUUID(),
    createdAt:
      signal.createdAt instanceof Date ? signal.createdAt : signal.createdAt ? new Date(signal.createdAt) : new Date(),
    acceptedAt:
      signal.acceptedAt instanceof Date
        ? signal.acceptedAt
        : signal.acceptedAt
          ? new Date(signal.acceptedAt)

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set `type` to a supported value, e.g. `createSignal({ type: 'reactive', contents: ... })` for reactive signals.
2. For a custom XML-tag signal, provide `tagName` explicitly: `createSignal({ type: 'custom', tagName: 'my-tag', contents: ... })` (verify the exact custom type name in signals.ts).
3. Validate signal types coming from config/user input before calling createSignal.
4. Check the AgentSignalInput type union for the exact accepted literals and keep your code in sync after upgrades.

Example fix

// before
createSignal({ type: 'note', contents: 'hello' });
// after
createSignal({ type: 'reactive', contents: 'hello' }); // or use the custom-tag type with tagName

const SIGNAL_TYPES = ['reactive', 'state', 'custom'] as const; // check signals.ts for exact union
if (!SIGNAL_TYPES.includes(input.type)) {
  throw new TypeError(`signal type must be one of ${SIGNAL_TYPES.join(', ')}`);
}

function isValidSignalType(t: string): boolean {
  return ['reactive', 'state', 'custom'].includes(t);
}

try {
  const signal = createSignal(input);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid signal type')) {
    signal = createSignal({ ...input, type: 'reactive' });
  } else throw e;
}

When it happens

Trigger: Calling createSignal()/createAgentSignal with `type` set to something other than the supported values (e.g. 'custom', 'note', a typo like 'reacttive'), or relying on a custom tag type without setting `tagName`.

Common situations: Migrating from an older signal API with different type names; typos in signal type literals; constructing signal objects from user/config input without validating the type; passing a UI data-part type that isn't a recognized signal type.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid signal XML ${label}: ${name}
• A numeric theme id is required
• A theme snapshot is required
• Noise example queries require a trace signal and snapshot
• Noise queries require a trace signal and snapshot

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