mastra-ai/mastra · error · MastraError

SCHEDULES_INVALID_ID

SCHEDULES_INVALID_ID

Error message

schedules.create: id "${rawId}" is empty after normalization. Provide an id with at least one alphanumeric character.

What it means

`normalizeScheduleId` in packages/core/src/schedules/schedules.ts:41 slugifies the caller-supplied schedule id into a canonical `<prefix><slug>` form. If nothing slug-able remains (no alphanumeric characters survive trimming/slugification), the id cannot be addressed in storage or URLs, so `SCHEDULES_INVALID_ID` is thrown to prevent creating an unaddressable schedule. It is a 400-class user error from `schedules.create` (and other id-consuming paths).

Source

Thrown at packages/core/src/schedules/schedules.ts:41

 * string when nothing slug-able remains.
 */
function canonicalizeScheduleId(rawId: string, prefix: string): string {
  const trimmed = rawId.trim();
  const withoutPrefix = trimmed.startsWith(prefix) ? trimmed.slice(prefix.length) : trimmed;
  const slug = slugify(withoutPrefix);
  if (!slug) return '';
  return `${prefix}${slug}`;
}

/**
 * Normalize a caller-supplied schedule id for `create`. Throws
 * `SCHEDULES_INVALID_ID` when the id is empty after normalization so callers
 * cannot create an unaddressable schedule.
 */
function normalizeScheduleId(rawId: string, prefix: string): string {
  const canonical = canonicalizeScheduleId(rawId, prefix);
  if (!canonical) {
    throw new MastraError({
      id: 'SCHEDULES_INVALID_ID',
      domain: ErrorDomain.AGENT,
      category: ErrorCategory.USER,
      details: { status: 400 },
      text: `schedules.create: id "${rawId}" is empty after normalization. Provide an id with at least one alphanumeric character.`,
    });
  }
  return canonical;
}

/**
 * Flat agent-schedule view returned by the {@link Schedules} service.
 * Projects the underlying `Schedule` row + `target.type === 'agent'` payload
 * onto a single object so callers never have to know about the schedules
 * storage shape. Discriminate from {@link WorkflowSchedule} via the
 * `agentId` field.
 */
export interface AgentSchedule {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an id containing at least one alphanumeric character (e.g. `nightly-summary`); the `agent_`/`workflow_` prefix is optional since it is added if missing.
2. Sanitize/validate the id with the same slugify rules before calling create and fall back to a generated id (e.g. randomUUID) when the slug would be empty.
3. Check for empty/undefined inputs feeding a dynamic id template string.

Example fix

// before
const id = `schedule-${config.name ?? ''}`.toLowerCase(); // could be 'schedule-'
schedules.create({ id, agentId, prompt, cron });

// after
const slug = slugify(config.name ?? '');
if (!slug) throw new Error('config.name must contain alphanumeric characters');
schedules.create({ id: slug, agentId, prompt, cron });

function isValidScheduleId(raw) {
  return typeof raw === 'string' && /[a-z0-9]/i.test(raw);
}
if (!isValidScheduleId(id)) throw new Error(`Invalid schedule id: ${JSON.stringify(id)}`);

function isNonEmptySlugId(id: unknown): id is string {
  return typeof id === 'string' && /[a-zA-Z0-9]/.test(id);
}

try {
  await schedules.create({ id, ...input });
} catch (e) {
  if (e instanceof MastraError && e.id === 'SCHEDULES_INVALID_ID') {
    throw new Error(`Schedule id "${input.id ?? ''}" normalizes to empty; use an id with alphanumeric characters`);
  }
  throw e;
}

When it happens

Trigger: Calling `schedules.create({ id: ... })` where the id normalizes to empty: an empty string, whitespace only (`' '`), a string of only punctuation/symbols (`'---'`, `'___'`, `'###'`), or a string consisting solely of the prefix (e.g. `id: 'agent_'` for an agent schedule).

Common situations: Building ids dynamically from data (template strings interpolating empty/undefined-ish values), stripping characters during sanitization until only separators remain, passing a variable that is empty at runtime, or passing only the `agent_`/`workflow_` prefix assuming it counts as an id.

Related errors

• SCHEDULES_INVALID_DEFINITION
• SCHEDULES_AMBIGUOUS_MODE
• SCHEDULES_MISSING_MODE
• SCHEDULES_INVALID_SIGNAL_TYPE
• SCHEDULES_INVALID_STATUS

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