{"record":{"id":"4b2528dcce71490e","repo":"mastra-ai/mastra","slug":"schedules-invalid-cron","errorCode":"SCHEDULES_INVALID_CRON","errorMessage":"Schedule${where}: ${error instanceof Error ? error.message : String(error)}","messagePattern":"Schedule(.+?): (.+?)","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/schedules/define.ts","lineNumber":190,"sourceCode":"      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)}`,\n      },\n      error,\n    );\n  }\n\n  // Markdown schedules never pass through TypeScript, so these enum-ish fields\n  // are only checked here. An unchecked value would reach schedule storage and\n  // surface as a confusing runtime failure on the first fire.\n  if (definition.signalType !== undefined && !SCHEDULE_SIGNAL_TYPES.includes(definition.signalType)) {\n    throw new MastraError({\n      id: 'SCHEDULES_INVALID_SIGNAL_TYPE',\n      domain: ErrorDomain.AGENT,","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/schedules/define.ts#L172-L208","documentation":"The schedule's 'cron' expression (or its 'timezone') failed validation by validateCron, and the underlying parser message is re-thrown as a MastraError with the SCHEDULES_INVALID_CRON id. Mastra validates the cron and timezone eagerly in assertValidScheduleDefinition so an invalid expression is caught at definition/build time rather than at the first scheduled fire. The original validator message is embedded in the error text, and details include the offending cron string.","triggerScenarios":"Passing a malformed cron expression (wrong field count, out-of-range values, invalid step/list characters) to defineSchedule or a file-based schedule; passing a cron string paired with an unrecognized IANA timezone; passing a non-string cron value that String()-coerces to something unparseable, via resolveSchedules.","commonSituations":"Hand-writing a 5-field cron with 6 fields or vice versa when the parser expects one specific format; using '@daily' style macros or seconds fields unsupported by the validator; typo'd timezone like 'UTC+2' or 'America/Orlando' instead of a valid IANA zone; markdown schedules where TS types can't catch the bad value.","solutions":["Read the embedded validator message and fix the cron expression accordingly (correct number of fields, in-range values).","Verify the timezone is a valid IANA name (e.g. 'America/New_York'); remove the timezone field if not needed.","Test the expression with a cron validator or the same parser library before deploying.","If the cron is dynamically built, log/inspect the final string — coerced non-string values often produce garbage like 'undefined'."],"exampleFix":"// before\ndefineSchedule({ cron: '0 9 * ', timezone: 'UTC+2' });\n// after\ndefineSchedule({ cron: '0 9 * * *', timezone: 'UTC' });","handlingStrategy":"validation","validationCode":"function isValidCron(cron, timezone) {\n  try { validateCron(cron, timezone); return true; } catch { return false; }\n}\nif (!isValidCron('0 9 * * *', 'UTC')) throw new Error('Invalid cron/timezone before defining schedule');","typeGuard":null,"tryCatchPattern":"try {\n  const schedule = defineSchedule({ cron: myCron, timezone: myTz, prompt });\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'SCHEDULES_INVALID_CRON') {\n    // e.message contains the underlying parser message; log cron and fix the expression\n  } else throw e;\n}","preventionTips":["Validate cron expressions with a cron parser/validator before committing them.","Use only valid IANA timezone names (e.g. from Intl.supportedValuesOf('timeZone')).","Avoid exotic cron syntax (macros, seconds fields) unless the validator documents support.","For dynamic crons, log the final string and assert it matches /\\S+(\\s+\\S+){4}$/ before use."],"tags":["schedules","cron","configuration","validation"],"backgroundTag":"invalid-cron-expression","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}