mastra-ai/mastra · error · MastraError

SCHEDULES_INVALID_DEFINITION

SCHEDULES_INVALID_DEFINITION

Error message

Schedule${where}: expected a schedule definition object, received ${definition === null ? 'null' : typeof definition}.

What it means

Thrown by `assertValidScheduleDefinition` when an agent schedule definition is not a non-null object. Schedules for agents must be defined as objects (e.g. `{ type: 'cron', ... }` or `{ type: 'date', ... }`); passing null, a string, or a primitive fails this assertion. The optional `label` identifies where in assembly the bad definition was found (e.g. `agents/<id>/schedules/<key>`).

Source

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

): AgentScheduleDefinition<TMastra> {
  assertValidScheduleDefinition(definition);
  return definition;
}

/**
 * Validate a schedule definition, throwing a `MastraError` naming the offending
 * schedule. Shared by `defineSchedule` (author-time) and file-based agent
 * assembly (build-time, where markdown schedules never went through
 * `defineSchedule`).
 *
 * `label` describes the schedule in error text — `defineSchedule` has no
 * identity to report, so assembly passes `agents/<id>/schedules/<key>`.
 */
export function assertValidScheduleDefinition(definition: AgentScheduleDefinition<any>, label?: string): void {
  const where = label ? ` (${label})` : '';

  if (!definition || typeof definition !== 'object') {
    throw new MastraError({
      id: 'SCHEDULES_INVALID_DEFINITION',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '' },
      text: `Schedule${where}: expected a schedule definition object, received ${definition === null ? 'null' : typeof definition}.`,
    });
  }

  const hasPrompt = typeof definition.prompt === 'string' && definition.prompt.trim() !== '';
  const hasHandler = typeof definition.handler === 'function';

  if (hasPrompt && hasHandler) {
    throw new MastraError({
      id: 'SCHEDULES_AMBIGUOUS_MODE',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '' },
      text: `Schedule${where}: set exactly one execution mode — remove either 'prompt' or 'handler'.`,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Wrap the value in a proper definition object, e.g. `{ type: 'cron', expression: '0 9 * * *' }` or `{ type: 'date', date: someDate }`.
2. Check the `label` in the error/details to find which agent schedule key holds the bad value.
3. Fix the source of the null/undefined (missing env var, failed JSON parse, wrong config key) before registration.
4. Validate the loaded schedule config shape before passing it to the agent constructor.

Example fix

// before
new Agent({
  schedules: { dailyReport: '0 9 * * *' }, // string, not object
});

// after
new Agent({
  schedules: { dailyReport: { type: 'cron', expression: '0 9 * * *' } },
});

function isValidScheduleDefinition(d: unknown): d is AgentScheduleDefinition<any> {
  return !!d && typeof d === 'object' && !Array.isArray(d) && 'type' in d;
}

// before registration:
Object.entries(scheduleConfig).forEach(([key, def]) => {
  if (!isValidScheduleDefinition(def)) {
    throw new Error(`Schedule ${key} must be a definition object, got ${def === null ? 'null' : typeof def}`);
  }
});

function isScheduleDefinition(v: unknown): v is AgentScheduleDefinition<any> {
  return (
    typeof v === 'object' && v !== null && !Array.isArray(v) &&
    ((v as any).type === 'cron' || (v as any).type === 'date')
  );
}

try {
  const agent = new Agent({ schedules: scheduleConfig });
} catch (e) {
  if (e instanceof MastraError && e.id === 'SCHEDULES_INVALID_DEFINITION') {
    console.error(`Bad schedule config at ${e.details?.label}; falling back to default schedules.`);
    return new Agent({});
  }
  throw e;
}

When it happens

Trigger: `defineSchedule`/`resolveSchedules` (via agent schedule registration) receives `definition` that is `null`, `undefined`, a string like `'0 9 * * *'` passed directly, a number, or a boolean instead of a schedule definition object.

Common situations: Passing a bare cron expression string instead of `{ type: 'cron', expression: '...' }`; a config file where the schedule value is null due to a failed env/JSON lookup; dynamically loaded schedule config from a DB/API that returned null; typos in config keys yielding undefined.

Related errors

• SCHEDULES_MISSING_RESOURCE_ID
• SCHEDULES_MISSING_TARGET_ID
• SCHEDULES_AMBIGUOUS_MODE
• SCHEDULES_MISSING_MODE
• SCHEDULES_INVALID_SIGNAL_TYPE

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