mastra-ai/mastra · error · HTTPException

Stored resource scope is required

Error message

Stored resource scope is required

What it means

Agent-version stored-resource routes require that the resource scope (a resource id used as a metadata scoping key) be resolvable from the request. getStoredResourceScope throws HTTP 403 when no scope can be resolved from the request context or headers and the caller did not opt out via options.requireScope === false. This prevents leaking or mutating stored resources across resource boundaries.

Source

Thrown at packages/server/src/server/utils.ts:85

  requestContext: RequestContext | undefined,
): Promise<StoredResourceScope | undefined> {
  const scopeConfig = mastra?.getServer?.()?.storedResources?.scope;
  if (!scopeConfig) {
    return undefined;
  }

  const options = scopeConfig === true ? {} : scopeConfig;
  const metadataKey = options.metadataKey ?? DEFAULT_STORED_RESOURCE_SCOPE_METADATA_KEY;
  const user = requestContext?.get('user');
  const resolved = options.resolve
    ? await options.resolve({ requestContext, user })
    : (requestContext?.get(MASTRA_RESOURCE_ID_KEY) as string | undefined);

  if (!resolved) {
    if (options.requireScope === false) {
      return undefined;
    }
    throw new HTTPException(403, { message: 'Stored resource scope is required' });
  }

  return { metadataKey, value: resolved };
}

export function scopeStoredResourceMetadata(
  metadata: Record<string, unknown> | undefined,
  scope: StoredResourceScope | undefined,
): Record<string, unknown> | undefined {
  if (!scope) {
    return metadata;
  }

  return {
    ...(metadata ?? {}),
    [scope.metadataKey]: scope.value,
  };
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Send the resource id header (x-mastra-resource-id) with the request
2. Ensure your auth/context middleware sets the MASTRA_RESOURCE_ID_KEY in requestContext for these routes
3. If the deployment intentionally has no resource scoping, configure the route/context with requireScope: false

Example fix

// before
curl http://localhost:4111/api/agents/myAgent/versions
// after
curl -H 'x-mastra-resource-id: tenant-1' http://localhost:4111/api/agents/myAgent/versions

if (!process.env.DEFAULT_RESOURCE_ID && !requestHeaders['x-mastra-resource-id']) {
  throw new Error('Resource id must be provided for agent-version APIs');
}

const hasScope = (ctx: { get(k: string): unknown }): boolean =>
  typeof ctx.get('MASTRA_RESOURCE_ID_KEY') === 'string';

When it happens

Trigger: Hitting any agent-version route (LIST/CREATE/GET/ACTIVATE/RESTORE/DELETE_AGENT_VERSIONS) without providing a resource id (e.g. the x-mastra-resource-id header) and without requestContext containing MASTRA_RESOURCE_ID_KEY.

Common situations: Calling agent-version REST endpoints with curl/scripts that omit the resource-id header; server middleware not propagating the resource id into requestContext; misconfigured auth that no longer sets MASTRA_RESOURCE_ID_KEY after an upgrade.

Related errors

• Stored resource not found
• invalid API key or insufficient permissions
• Attaching a database requires the admin role in your organiz
• You need the admin role in this organization to manage datab
• Agents storage domain is not available

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