mastra-ai/mastra · error · MastraError

SCHEDULES_MISSING_MODE

SCHEDULES_MISSING_MODE

Error message

Schedule${where}: set exactly one execution mode — provide a non-empty 'prompt' or a 'handler' function.

What it means

A schedule definition provided neither a non-empty 'prompt' nor a 'handler' function, so Mastra cannot determine how the schedule should execute. This is thrown at definition/assembly time by assertValidScheduleDefinition so the misconfiguration surfaces at import/build time instead of failing silently on the first cron fire. A whitespace-only prompt string counts as empty and triggers this error.

Source

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

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

  if (!hasPrompt && !hasHandler) {
    throw new MastraError({
      id: 'SCHEDULES_MISSING_MODE',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { label: label ?? '' },
      text: `Schedule${where}: set exactly one execution mode — provide a non-empty 'prompt' or a 'handler' function.`,
    });
  }

  try {
    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)}`,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a non-empty 'prompt' string describing what the agent should do on each fire.
2. Add a 'handler' function if the schedule should run code instead of a prompt.
3. Check the field spelling ('prompt'/'handler') and that the handler is actually a function (verify imports resolve to a function, not undefined).
4. If the prompt is generated, guard against empty/whitespace results before defining the schedule.

Example fix

// before
defineSchedule({
  cron: '0 9 * * *',
});
// after
defineSchedule({
  cron: '0 9 * * *',
  prompt: 'Check system health and report any failures.',
});

function hasExecMode(def) {
  const hasPrompt = typeof def?.prompt === 'string' && def.prompt.trim() !== '';
  const hasHandler = typeof def?.handler === 'function';
  return hasPrompt || hasHandler;
}
if (!hasExecMode(mySchedule)) throw new Error('Provide a non-empty prompt or a handler function');

function hasAMode(def: { prompt?: string; handler?: unknown }): boolean {
  return (typeof def.prompt === 'string' && def.prompt.trim() !== '') || typeof def.handler === 'function';
}

try {
  const schedule = defineSchedule(def);
} catch (e) {
  if (e instanceof MastraError && e.id === 'SCHEDULES_MISSING_MODE') {
    // add a prompt or handler, or fail fast with a clear config message
  } else throw e;
}

When it happens

Trigger: Calling defineSchedule({cron}) with only a cron expression; setting prompt: '' or prompt: ' ' (whitespace-only); setting handler to a non-function value (e.g. an async result or undefined after a bad import); a markdown/file-based schedule object missing both fields passed to resolveSchedules.

Common situations: Deleting the handler body during refactoring and leaving the object with neither field; an environment-conditional import returning undefined for the handler; typo'd field names (e.g. 'handlers' or 'prompts') that TypeScript cannot catch in markdown-defined schedules; empty prompt built from a template literal that evaluated to an empty string.

Related errors

• SCHEDULES_AMBIGUOUS_MODE
• SCHEDULES_INVALID_DEFINITION
• SCHEDULES_INVALID_CRON
• SCHEDULES_INVALID_SIGNAL_TYPE
• SCHEDULES_INVALID_STATUS

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