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.

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.

Appendix: 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)