mastra-ai/mastra · error · MastraError

SCHEDULES_INVALID_STATUS

SCHEDULES_INVALID_STATUS

Error message

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

What it means

The schedule definition's 'status' field was set to a value not in the SCHEDULE_STATUSES allowlist. Like signalType, status is only runtime-validated (markdown schedules bypass TypeScript), so assertValidScheduleDefinition rejects unknown values at definition/build time to prevent a confusing failure in schedule storage or on the first fire. The error message enumerates all valid statuses.

Solutions

1. Set status to one of the values listed in the error message (the SCHEDULE_STATUSES allowlist).
2. Remove the status field entirely — it is optional and defaults apply.
3. Fix casing/spelling exactly against the allowlist values.
4. After a version upgrade, re-check any schedules that set status explicitly against the current enum.

Example fix

// before
defineSchedule({ cron: '0 9 * * *', prompt: 'Run', status: 'enabled' });
// after
defineSchedule({ cron: '0 9 * * *', prompt: 'Run', status: 'active' }); // use a value from SCHEDULE_STATUSES

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

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

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

When it happens

Trigger: Calling defineSchedule with status set to a misspelled or unsupported value (e.g. 'enabled'/'running' when the allowlist expects 'active'/'paused'-style values); a markdown/file-based schedule with an invalid status passed through resolveSchedules; a version change where the status enum was renamed.

Common situations: Guessing status names instead of checking the type/docs; hand-editing markdown schedules; copy-pasting a status string from another scheduling system (e.g. 'DISABLED' with wrong casing); migrating schedules between Mastra versions with renamed statuses.

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

• SCHEDULES_INVALID_SIGNAL_TYPE
• SCHEDULES_AMBIGUOUS_MODE
• SCHEDULES_INVALID_DEFINITION
• SCHEDULES_INVALID_ID
• SCHEDULES_MISSING_MODE

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

Appendix: source

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

      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(', ')}.`,
    });
  }

  if (definition.threadId && !definition.resourceId) {
    throw new MastraError({
      id: 'SCHEDULES_MISSING_RESOURCE_ID',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '' },
      text: `Schedule${where}: 'resourceId' is required when 'threadId' is set.`,
    });
  }
}

View on GitHub (pinned to 75dd419e61)