{"record":{"id":"7abf24400acdbe06","repo":"mastra-ai/mastra","slug":"unable-to-verify-referenced-prompt-blocks-unres","errorCode":null,"errorMessage":"Unable to verify referenced prompt blocks: ${unresolvedIds.join(', ')}. Resolve these references and try again.","messagePattern":"Unable to verify referenced prompt blocks: (.+?)\\. Resolve these references and try again\\.","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/validate-agent-instructions.ts","lineNumber":86,"sourceCode":"    if (!id || result.status === 'rejected' || !result.value) {\n      if (id) unresolvedIds.push(id);\n      continue;\n    }\n\n    try {\n      assertStoredResourceScope(result.value, scope);\n    } catch {\n      unresolvedIds.push(id);\n      continue;\n    }\n\n    if (result.value.status !== 'published' || !result.value.activeVersionId) {\n      unpublishedIds.push(id);\n    }\n  }\n\n  if (unresolvedIds.length > 0) {\n    throw new HTTPException(400, {\n      message: `Unable to verify referenced prompt blocks: ${unresolvedIds.join(', ')}. Resolve these references and try again.`,\n    });\n  }\n\n  if (unpublishedIds.length > 0) {\n    throw new HTTPException(400, {\n      message: UNPUBLISHED_REFERENCES_MESSAGE.replace('{ids}', unpublishedIds.join(', ')),\n    });\n  }\n}\n","sourceCodeStart":68,"sourceCodeEnd":97,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/validate-agent-instructions.ts#L68-L97","documentation":"HTTP 400 thrown by validateAgentInstructionReferences when one or more prompt blocks referenced in an agent's instructions cannot be resolved (not found or not verifiable). The server refuses to create/update/activate the agent version because instructions would contain dangling references. The message lists the unresolved block IDs.","triggerScenarios":"POST/PUT to stored-agent routes or the activate-agent-version route with instructions containing block references whose IDs do not resolve via the storage lookup (e.g. deleted blocks, mistyped IDs, wrong scope/namespace).","commonSituations":"Referencing prompt blocks that were deleted after being written into agent instructions; typos or copy-paste of IDs from another environment; multi-tenant setups where blocks live in a different project; exporting agent configs between deployments without their blocks.","solutions":["Fix or remove the listed reference IDs in the agent's instructions (IDs are enumerated in the error message).","Create the missing prompt blocks first, then retry the request.","Verify the block IDs exist in the same server/tenant by fetching the blocks list before saving the agent."],"exampleFix":"// before\ninstructions: 'Use {{block:prompt-abc}} for tone'\n// after\ninstructions: 'Use {{block:prompt-123}} for tone' // prompt-123 exists and is published","handlingStrategy":"validation","validationCode":"const refs = [...instructions.matchAll(/\\{\\{block:([\\w-]+)\\}\\}/g)].map(m => m[1]);\nconst blocks = await fetch('/api/blocks').then(r => r.json());\nconst missing = refs.filter(id => !blocks.some(b => b.id === id));\nif (missing.length) throw new Error(`Unresolved block refs: ${missing.join(', ')}`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a single source of truth for block IDs and reference them via generated constants.","Validate all instruction references before saving agent configs.","Run a pre-deploy check that every referenced block exists in the target environment."],"tags":["http-400","validation","agent-instructions","references"],"backgroundTag":"unresolved-reference","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}