mastra-ai/mastra · error · MastraError

SCHEDULES_INVALID_SIGNAL_TYPE

SCHEDULES_INVALID_SIGNAL_TYPE

Error message

Schedule${where}: unknown signalType "${definition.signalType}". Expected one of: ${SCHEDULE_SIGNAL_TYPES.join(', ')}.

What it means

The schedule definition's 'signalType' field was set to a value not in the SCHEDULE_SIGNAL_TYPES allowlist. Because markdown-defined schedules never pass through TypeScript checking, Mastra validates these enum-like fields at runtime in assertValidScheduleDefinition; an unchecked value would otherwise reach schedule storage and fail confusingly on the first fire. The error lists all valid signalType values.

Source

Thrown at packages/core/src/schedules/define.ts:206

    validateCron(definition.cron, definition.timezone);
  } catch (error) {
    throw new MastraError(
      {
        id: 'SCHEDULES_INVALID_CRON',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        details: { label: label ?? '', cron: String(definition.cron) },
        text: `Schedule${where}: ${error instanceof Error ? error.message : String(error)}`,
      },
      error,
    );
  }

  // Markdown schedules never pass through TypeScript, so these enum-ish fields
  // are only checked here. An unchecked value would reach schedule storage and
  // surface as a confusing runtime failure on the first fire.
  if (definition.signalType !== undefined && !SCHEDULE_SIGNAL_TYPES.includes(definition.signalType)) {
    throw new MastraError({
      id: 'SCHEDULES_INVALID_SIGNAL_TYPE',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '', signalType: String(definition.signalType) },
      text: `Schedule${where}: unknown signalType "${definition.signalType}". Expected one of: ${SCHEDULE_SIGNAL_TYPES.join(', ')}.`,
    });
  }

  if (definition.status !== undefined && !SCHEDULE_STATUSES.includes(definition.status)) {
    throw new MastraError({
      id: 'SCHEDULES_INVALID_STATUS',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '', status: String(definition.status) },
      text: `Schedule${where}: unknown status "${definition.status}". Expected one of: ${SCHEDULE_STATUSES.join(', ')}.`,
    });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Set signalType to one of the values listed in the error message (the SCHEDULE_SIGNAL_TYPES allowlist).
Remove the signalType field entirely if the default is acceptable (it is optional).
Fix the spelling/casing — enum values are matched exactly, not case-insensitively.
If migrating between versions, check the changelog for renamed signalType values and update the schedule.

Example fix

// before
defineSchedule({ cron: '0 9 * * *', prompt: 'Run', signalType: 'cron-start' });
// after
defineSchedule({ cron: '0 9 * * *', prompt: 'Run' }); // or use a listed signalType value

Defensive patterns

Strategy: validation

Validate before calling

import { SCHEDULE_SIGNAL_TYPES } from '@mastra/core/schedules';
if (mySchedule.signalType !== undefined && !SCHEDULE_SIGNAL_TYPES.includes(mySchedule.signalType)) {
  throw new Error(`signalType must be one of: ${SCHEDULE_SIGNAL_TYPES.join(', ')}`);
}

Type guard

function isValidSignalType(v: unknown): v is (typeof SCHEDULE_SIGNAL_TYPES)[number] {
  return SCHEDULE_SIGNAL_TYPES.includes(v as any);
}

Try / catch

try {
  const schedule = defineSchedule(def);
} catch (e) {
  if (e instanceof MastraError && e.id === 'SCHEDULES_INVALID_SIGNAL_TYPE') {
    // map/normalize the value to an allowed one or drop the field
  } else throw e;
}

Prevention

Import SCHEDULE_SIGNAL_TYPES and pick values from it instead of typing strings by hand.
Omit signalType when the default is fine — the field is optional.
For markdown/file-based schedules, run resolveSchedules in CI so runtime validation catches bad enums before deploy.
Re-check enum values after Mastra version upgrades.

When it happens

Trigger: Calling defineSchedule({cron, prompt, signalType: '...'}) with a misspelled or unsupported signalType; a file-based/markdown schedule carrying an invalid signalType passed through resolveSchedules; upgrading/downgrading versions where the allowed set changed and an old value is no longer recognized.

Common situations: Typo such as 'signelType' value 'once' vs a required enum member, or copying a signalType from a different Mastra area with a different enum; hand-editing a markdown schedule with a guessed value; docs/examples from an older version using a renamed enum value.

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

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