{"record":{"id":"9b18ce6b028790ab","repo":"mastra-ai/mastra","slug":"schedules-missing-mode","errorCode":"SCHEDULES_MISSING_MODE","errorMessage":"Schedule${where}: set exactly one execution mode — provide a non-empty 'prompt' or a 'handler' function.","messagePattern":"Schedule(.+?): set exactly one execution mode — provide a non-empty 'prompt' or a 'handler' function\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/schedules/define.ts","lineNumber":178,"sourceCode":"      text: `Schedule${where}: expected a schedule definition object, received ${definition === null ? 'null' : typeof definition}.`,\n    });\n  }\n\n  const hasPrompt = typeof definition.prompt === 'string' && definition.prompt.trim() !== '';\n  const hasHandler = typeof definition.handler === 'function';\n\n  if (hasPrompt && hasHandler) {\n    throw new MastraError({\n      id: 'SCHEDULES_AMBIGUOUS_MODE',\n      domain: ErrorDomain.AGENT,\n      category: ErrorCategory.USER,\n      details: { label: label ?? '' },\n      text: `Schedule${where}: set exactly one execution mode — remove either 'prompt' or 'handler'.`,\n    });\n  }\n\n  if (!hasPrompt && !hasHandler) {\n    throw new MastraError({\n      id: 'SCHEDULES_MISSING_MODE',\n      domain: ErrorDomain.AGENT,\n      category: ErrorCategory.USER,\n      details: { label: label ?? '' },\n      text: `Schedule${where}: set exactly one execution mode — provide a non-empty 'prompt' or a 'handler' function.`,\n    });\n  }\n\n  try {\n    validateCron(definition.cron, definition.timezone);\n  } catch (error) {\n    throw new MastraError(\n      {\n        id: 'SCHEDULES_INVALID_CRON',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        details: { label: label ?? '', cron: String(definition.cron) },\n        text: `Schedule${where}: ${error instanceof Error ? error.message : String(error)}`,","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/schedules/define.ts#L160-L196","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add a non-empty 'prompt' string describing what the agent should do on each fire.","Add a 'handler' function if the schedule should run code instead of a prompt.","Check the field spelling ('prompt'/'handler') and that the handler is actually a function (verify imports resolve to a function, not undefined).","If the prompt is generated, guard against empty/whitespace results before defining the schedule."],"exampleFix":"// before\ndefineSchedule({\n  cron: '0 9 * * *',\n});\n// after\ndefineSchedule({\n  cron: '0 9 * * *',\n  prompt: 'Check system health and report any failures.',\n});","handlingStrategy":"validation","validationCode":"function hasExecMode(def) {\n  const hasPrompt = typeof def?.prompt === 'string' && def.prompt.trim() !== '';\n  const hasHandler = typeof def?.handler === 'function';\n  return hasPrompt || hasHandler;\n}\nif (!hasExecMode(mySchedule)) throw new Error('Provide a non-empty prompt or a handler function');","typeGuard":"function hasAMode(def: { prompt?: string; handler?: unknown }): boolean {\n  return (typeof def.prompt === 'string' && def.prompt.trim() !== '') || typeof def.handler === 'function';\n}","tryCatchPattern":"try {\n  const schedule = defineSchedule(def);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'SCHEDULES_MISSING_MODE') {\n    // add a prompt or handler, or fail fast with a clear config message\n  } else throw e;\n}","preventionTips":["Always set either prompt or handler when authoring a schedule; treat cron-only objects as incomplete.","Verify handler imports resolve to functions (a bad import silently yields undefined).","Trim/validate dynamically generated prompts before assigning them.","Rely on defineSchedule()'s author-time validation rather than defining schedules as plain objects in markdown/files."],"tags":["schedules","configuration","validation","user-error"],"backgroundTag":"missing-schedule-execution-mode","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}