What causes "Version with id ${versionId} not found" in mastra-ai/mastra?

mastra-ai/mastra · error · HTTPException

Version with id ${versionId} not found

Error message

Version with id ${versionId} not found

What it means

The handler fetches the version by versionId; if none exists it returns a 404 naming the version id. Note the lookup is done by versionId alone first, and the promptBlockId match is checked separately (error 2896), so this message strictly means the version id is unknown to the store.

Source

Thrown at packages/server/src/server/handlers/prompt-block-versions.ts:194

  description: 'Returns a specific version of a prompt block by its version ID',
  tags: ['Prompt Block Versions'],
  handler: async ({ mastra, promptBlockId, versionId, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const promptBlockStore = await storage.getStore('promptBlocks');
      if (!promptBlockStore) {
        throw new HTTPException(500, { message: 'Prompt blocks storage domain is not available' });
      }

      const version = await promptBlockStore.getVersion(versionId);

      if (!version) {
        throw new HTTPException(404, { message: `Version with id ${versionId} not found` });
      }

      if (version.blockId !== promptBlockId) {
        throw new HTTPException(404, {
          message: `Version with id ${versionId} not found for prompt block ${promptBlockId}`,
        });
      }
      const promptBlock = await promptBlockStore.getById(promptBlockId);
      assertStoredResourceScope(promptBlock, await getStoredResourceScope(mastra, requestContext));

      return version;
    } catch (error) {
      return handleError(error, 'Error getting prompt block version');
    }
  },
});

/**

View on GitHub (pinned to 75dd419e61)

Solutions

List current versions via GET /stored/prompt-blocks/:promptBlockId/versions and use an existing versionId.
Verify the version wasn't pruned by the retention policy (max versions) and raise the limit if history must be kept.
Confirm the id is complete and not truncated (uuid copy/paste errors).
Check you are querying the same storage/database where the version was created.

Example fix

// before
await fetch(`/api/stored/prompt-blocks/${blockId}/versions/${guessedVersionId}`);
// after
const { versions } = await fetch(`/api/stored/prompt-blocks/${blockId}/versions`).then(r => r.json());
const versionId = versions.find(v => v.changeMessage === 'initial')?.id;
await fetch(`/api/stored/prompt-blocks/${blockId}/versions/${versionId}`);

Defensive patterns

Strategy: validation

Validate before calling

const { versions } = await fetch(`/api/stored/prompt-blocks/${blockId}/versions`).then(r => r.json());
if (!versions.some(v => v.id === versionId)) throw new Error(`Version ${versionId} does not exist for block ${blockId}`);

Type guard

function isKnownVersionId(versions: { id: string }[], versionId: string): boolean {
  return versions.some(v => v.id === versionId);
}

Try / catch

try {
  await fetchVersion(blockId, versionId);
} catch (e) {
  if (e.status === 404 && e.message.startsWith('Version with id')) {
    const { versions } = await listVersions(blockId);
    versionId = versions[0]?.id; // fall back to latest
  } else throw e;
}

Prevention

Fetch version ids from listVersions rather than storing them long-term.
Raise retention limits if old versions must remain addressable.
Validate uuid format before calling the API.

When it happens

Trigger: GET /stored/prompt-blocks/:promptBlockId/versions/:versionId where getVersion(versionId) returns null — the version was never created, was deleted, or the id is malformed.

Common situations: Retention limits deleting old versions that a client still references; ids copied from logs of another environment; referencing a version of a deleted prompt block.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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