mastra-ai/mastra · error · HTTPException

Instructions are required

Error message

Instructions are required

What it means

assertOwnedInstructionsNotEmpty validates that the agent's instructions resolve to at least one non-empty text content block. createStoredAgentBodySchema/updates allow flexible instruction shapes (string or content blocks), so this runtime check enforces the invariant that a stored agent always has meaningful instructions. Thrown as HTTP 400 from POST /stored/agents and PUT/PATCH updates.

Source

Thrown at packages/server/src/server/handlers/stored-agents.ts:156

  }

  return value.some(block => {
    if (!block || typeof block !== 'object') {
      return false;
    }

    const typedBlock = block as { type?: unknown; id?: unknown; content?: unknown };
    if (typedBlock.type === 'prompt_block_ref') {
      return typeof typedBlock.id === 'string' && typedBlock.id.length > 0;
    }

    return typeof typedBlock.content === 'string' && typedBlock.content.trim().length > 0;
  });
}

function assertOwnedInstructionsNotEmpty(instructions: unknown) {
  if (!hasNonEmptyInstructions(instructions)) {
    throw new HTTPException(400, { message: 'Instructions are required' });
  }
}

function sortForStableJson(value: unknown): unknown {
  if (Array.isArray(value)) {
    return value.map(sortForStableJson);
  }

  if (value && typeof value === 'object' && !(value instanceof Date)) {
    return Object.fromEntries(
      Object.entries(value as Record<string, unknown>)
        .filter(([, entry]) => entry !== undefined)
        .sort(([left], [right]) => left.localeCompare(right))
        .map(([key, entry]) => [key, sortForStableJson(entry)]),
    );
  }

  return value;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide a non-empty instructions string in the request body
2. If using block-style instructions, include at least one text block whose content has non-whitespace characters
3. Trim and re-validate the instructions field client-side before submitting
4. For programmatic creation, default instructions explicitly (e.g. instructions ?? 'You are a helpful assistant')

Example fix

// before
await post('/stored/agents', { id: 'my-agent', instructions: '' });
// after
await post('/stored/agents', { id: 'my-agent', instructions: 'You are a helpful assistant.' });

function hasInstructions(i: unknown): boolean {
  if (typeof i === 'string') return i.trim().length > 0;
  if (Array.isArray(i)) return i.some(b => typeof b?.content === 'string' && b.content.trim().length > 0);
  return false;
}
if (!hasInstructions(body.instructions)) throw new Error('instructions required');

function hasNonEmptyInstructions(i: unknown): i is string | Array<{ type: 'text'; content: string }> {
  return typeof i === 'string'
    ? i.trim().length > 0
    : Array.isArray(i) && i.some(b => typeof (b as any)?.content === 'string' && (b as any).content.trim().length > 0);
}

try {
  await post('/stored/agents', body);
} catch (e) {
  if ((e as any).status === 400 && /Instructions are required/.test((e as any).message)) {
    body.instructions = body.instructions?.trim() || 'Default instructions';
    return post('/stored/agents', body);
  }
  throw e;
}

When it happens

Trigger: POST /stored/agents or UPDATE_STORED_AGENT_ROUTE with instructions = '' , instructions = [] , instructions containing only whitespace blocks (e.g. [{type:'text',content:' '}]), or instructions = null/undefined.

Common situations: A form/UI sends an empty instructions field; a migration or script copies agents and drops instructions; JSON body built programmatically with instructions: someVar where someVar is undefined; whitespace-only instructions pasted from a template.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• bad request: ${responseText}
• Invalid agent-builder action: ${actionId}. Valid actions are
• Invalid agent-builder action: ${actionId}
• Cannot delete the active version. Activate a different versi
• Agent ID is required

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