mastra-ai/mastra · error · HTTPException

Unable to use unpublished referenced prompt blocks: {ids}. P

Error message

Unable to use unpublished referenced prompt blocks: {ids}. Publish these prompt blocks and try again.

What it means

HTTP 400 thrown by validateAgentInstructionReferences when referenced prompt blocks resolve but are not in 'published' status (or lack an activeVersionId). The server blocks agent creation/update/activation until the referenced blocks are published. The message lists the unpublished block IDs via UNPUBLISHED_REFERENCES_MESSAGE.

Source

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

      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. Publish the listed prompt blocks (give them a published status/active version), then retry.
2. Reference a published version of the block instead of the draft.
3. Remove or replace the unpublished references in the agent instructions.

Example fix

// before
await fetch('/api/agents', { method: 'POST', body: JSON.stringify({ instructions: 'Use {{block:draft-block}}' }) });
// after
await publishBlock('draft-block'); // ensure status === 'published' && activeVersionId
await fetch('/api/agents', { method: 'POST', body: JSON.stringify({ instructions: 'Use {{block:draft-block}}' }) });

const blocks = await fetch('/api/blocks').then(r => r.json());
const unpublished = refs.filter(id => {
  const b = blocks.find(x => x.id === id);
  return !b || b.status !== 'published' || !b.activeVersionId;
});
if (unpublished.length) throw new Error(`Publish first: ${unpublished.join(', ')}`);

When it happens

Trigger: CREATE_STORED_AGENT_ROUTE, UPDATE_STORED_AGENT_ROUTE, or ACTIVATE_AGENT_VERSION_ROUTE with instructions referencing draft/unpublished prompt blocks.

Common situations: Drafting an agent alongside newly drafted blocks and forgetting to publish them; a collaborator unpublished a block after the agent was written; CI deploying agents against blocks still in review.

Related errors

• Unable to verify referenced prompt blocks: ${unresolvedIds.j
• 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/fe25db9e6f6ae977. Report an issue: GitHub.