{"record":{"id":"13a844b23ef6e405","repo":"mastra-ai/mastra","slug":"schedules-invalid-definition","errorCode":"SCHEDULES_INVALID_DEFINITION","errorMessage":"Schedule${where}: expected a schedule definition object, received ${definition === null ? 'null' : typeof definition}.","messagePattern":"Schedule(.+?): expected a schedule definition object, received (.+?)\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/schedules/define.ts","lineNumber":155,"sourceCode":"): AgentScheduleDefinition<TMastra> {\n  assertValidScheduleDefinition(definition);\n  return definition;\n}\n\n/**\n * Validate a schedule definition, throwing a `MastraError` naming the offending\n * schedule. Shared by `defineSchedule` (author-time) and file-based agent\n * assembly (build-time, where markdown schedules never went through\n * `defineSchedule`).\n *\n * `label` describes the schedule in error text — `defineSchedule` has no\n * identity to report, so assembly passes `agents/<id>/schedules/<key>`.\n */\nexport function assertValidScheduleDefinition(definition: AgentScheduleDefinition<any>, label?: string): void {\n  const where = label ? ` (${label})` : '';\n\n  if (!definition || typeof definition !== 'object') {\n    throw new MastraError({\n      id: 'SCHEDULES_INVALID_DEFINITION',\n      domain: ErrorDomain.AGENT,\n      category: ErrorCategory.USER,\n      details: { label: label ?? '' },\n      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'.`,","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/schedules/define.ts#L137-L173","documentation":"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>`).","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Wrap the value in a proper definition object, e.g. `{ type: 'cron', expression: '0 9 * * *' }` or `{ type: 'date', date: someDate }`.","Check the `label` in the error/details to find which agent schedule key holds the bad value.","Fix the source of the null/undefined (missing env var, failed JSON parse, wrong config key) before registration.","Validate the loaded schedule config shape before passing it to the agent constructor."],"exampleFix":"// before\nnew Agent({\n  schedules: { dailyReport: '0 9 * * *' }, // string, not object\n});\n\n// after\nnew Agent({\n  schedules: { dailyReport: { type: 'cron', expression: '0 9 * * *' } },\n});","handlingStrategy":"validation","validationCode":"function isValidScheduleDefinition(d: unknown): d is AgentScheduleDefinition<any> {\n  return !!d && typeof d === 'object' && !Array.isArray(d) && 'type' in d;\n}\n\n// before registration:\nObject.entries(scheduleConfig).forEach(([key, def]) => {\n  if (!isValidScheduleDefinition(def)) {\n    throw new Error(`Schedule ${key} must be a definition object, got ${def === null ? 'null' : typeof def}`);\n  }\n});","typeGuard":"function isScheduleDefinition(v: unknown): v is AgentScheduleDefinition<any> {\n  return (\n    typeof v === 'object' && v !== null && !Array.isArray(v) &&\n    ((v as any).type === 'cron' || (v as any).type === 'date')\n  );\n}","tryCatchPattern":"try {\n  const agent = new Agent({ schedules: scheduleConfig });\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'SCHEDULES_INVALID_DEFINITION') {\n    console.error(`Bad schedule config at ${e.details?.label}; falling back to default schedules.`);\n    return new Agent({});\n  }\n  throw e;\n}","preventionTips":["Never pass bare cron strings; always use `{ type: 'cron', expression }` or `{ type: 'date', date }`.","Coalesce nulls from env/config loaders before constructing agents.","Validate dynamically loaded schedule configs with a schema (zod) at startup."],"tags":["schedules","validation","config","user-error"],"backgroundTag":"schedule-definition-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}