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.

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)

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_INVALID_DEFINITION
• SCHEDULES_AMBIGUOUS_MODE
• SCHEDULES_MISSING_MODE
• SCHEDULES_MISSING_RESOURCE_ID

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