mastra-ai/mastra · error · HTTPException

Unable to verify referenced prompt blocks: ${unresolvedIds.j

Error message

Unable to verify referenced prompt blocks: ${unresolvedIds.join(', ')}. Resolve these references and try again.

What it means

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.

Source

Thrown at packages/server/src/server/handlers/validate-agent-instructions.ts:86

    if (!id || result.status === 'rejected' || !result.value) {
      if (id) unresolvedIds.push(id);
      continue;
    }

    try {
      assertStoredResourceScope(result.value, scope);
    } catch {
      unresolvedIds.push(id);
      continue;
    }

    if (result.value.status !== 'published' || !result.value.activeVersionId) {
      unpublishedIds.push(id);
    }
  }

  if (unresolvedIds.length > 0) {
    throw new HTTPException(400, {
      message: `Unable to verify referenced prompt blocks: ${unresolvedIds.join(', ')}. Resolve these references and try again.`,
    });
  }

  if (unpublishedIds.length > 0) {
    throw new HTTPException(400, {
      message: UNPUBLISHED_REFERENCES_MESSAGE.replace('{ids}', unpublishedIds.join(', ')),
    });
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fix or remove the listed reference IDs in the agent's instructions (IDs are enumerated in the error message).
2. Create the missing prompt blocks first, then retry the request.
3. Verify the block IDs exist in the same server/tenant by fetching the blocks list before saving the agent.

Example fix

// before
instructions: 'Use {{block:prompt-abc}} for tone'
// after
instructions: 'Use {{block:prompt-123}} for tone' // prompt-123 exists and is published

const refs = [...instructions.matchAll(/\{\{block:([\w-]+)\}\}/g)].map(m => m[1]);
const blocks = await fetch('/api/blocks').then(r => r.json());
const missing = refs.filter(id => !blocks.some(b => b.id === id));
if (missing.length) throw new Error(`Unresolved block refs: ${missing.join(', ')}`);

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Unable to use unpublished referenced prompt blocks: {ids}. P
• 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

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