{"record":{"id":"0b57d0269523a1a3","repo":"mastra-ai/mastra","slug":"instructions-are-required","errorCode":null,"errorMessage":"Instructions are required","messagePattern":"Instructions are required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/stored-agents.ts","lineNumber":156,"sourceCode":"  }\n\n  return value.some(block => {\n    if (!block || typeof block !== 'object') {\n      return false;\n    }\n\n    const typedBlock = block as { type?: unknown; id?: unknown; content?: unknown };\n    if (typedBlock.type === 'prompt_block_ref') {\n      return typeof typedBlock.id === 'string' && typedBlock.id.length > 0;\n    }\n\n    return typeof typedBlock.content === 'string' && typedBlock.content.trim().length > 0;\n  });\n}\n\nfunction assertOwnedInstructionsNotEmpty(instructions: unknown) {\n  if (!hasNonEmptyInstructions(instructions)) {\n    throw new HTTPException(400, { message: 'Instructions are required' });\n  }\n}\n\nfunction sortForStableJson(value: unknown): unknown {\n  if (Array.isArray(value)) {\n    return value.map(sortForStableJson);\n  }\n\n  if (value && typeof value === 'object' && !(value instanceof Date)) {\n    return Object.fromEntries(\n      Object.entries(value as Record<string, unknown>)\n        .filter(([, entry]) => entry !== undefined)\n        .sort(([left], [right]) => left.localeCompare(right))\n        .map(([key, entry]) => [key, sortForStableJson(entry)]),\n    );\n  }\n\n  return value;","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-agents.ts#L138-L174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide a non-empty instructions string in the request body","If using block-style instructions, include at least one text block whose content has non-whitespace characters","Trim and re-validate the instructions field client-side before submitting","For programmatic creation, default instructions explicitly (e.g. instructions ?? 'You are a helpful assistant')"],"exampleFix":"// before\nawait post('/stored/agents', { id: 'my-agent', instructions: '' });\n// after\nawait post('/stored/agents', { id: 'my-agent', instructions: 'You are a helpful assistant.' });","handlingStrategy":"validation","validationCode":"function hasInstructions(i: unknown): boolean {\n  if (typeof i === 'string') return i.trim().length > 0;\n  if (Array.isArray(i)) return i.some(b => typeof b?.content === 'string' && b.content.trim().length > 0);\n  return false;\n}\nif (!hasInstructions(body.instructions)) throw new Error('instructions required');","typeGuard":"function hasNonEmptyInstructions(i: unknown): i is string | Array<{ type: 'text'; content: string }> {\n  return typeof i === 'string'\n    ? i.trim().length > 0\n    : Array.isArray(i) && i.some(b => typeof (b as any)?.content === 'string' && (b as any).content.trim().length > 0);\n}","tryCatchPattern":"try {\n  await post('/stored/agents', body);\n} catch (e) {\n  if ((e as any).status === 400 && /Instructions are required/.test((e as any).message)) {\n    body.instructions = body.instructions?.trim() || 'Default instructions';\n    return post('/stored/agents', body);\n  }\n  throw e;\n}","preventionTips":["Validate instructions client-side (non-empty after trim) before submit","Make instructions a required field in forms/UIs","Default instructions in code that constructs agents programmatically","Cover instruction shape (string vs blocks) with unit tests"],"tags":["http-400","validation","stored-agents"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}