mastra-ai/mastra · error · Error

Knowledge tools require requestContext.organizationId.

Error message

Knowledge tools require requestContext.organizationId.

What it means

Subconscious knowledge tools resolve an access scope from requestContext: organizationId, resourceId, and threadId. The scope is [org:..., resource:..., thread:...]; without a non-empty organizationId string on requestContext the tools cannot scope knowledge access, so resolveScope throws before any storage access.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/knowledge-tools.ts:36

type KnowledgeToolsMemory = {
  storage: {
    getStore(name: 'knowledge'): Promise<KnowledgeStorage | undefined>;
  };
  getKnowledgeSemanticIndex(): Promise<KnowledgeSemanticIndexCoordinator>;
};

type KnowledgeToolContext = {
  agent?: { threadId?: string; resourceId?: string };
  requestContext?: { get(key: string): unknown };
};

function resolveScope(context: KnowledgeToolContext | undefined): KnowledgeScope {
  const organizationId = context?.requestContext?.get('organizationId');
  const resourceId = resolveKnowledgeResourceId(context?.requestContext, context?.agent?.resourceId);
  const threadId = context?.agent?.threadId;
  if (typeof organizationId !== 'string' || !organizationId.trim()) {
    throw new Error('Knowledge tools require requestContext.organizationId.');
  }
  if (!resourceId) throw new Error('Knowledge tools require an active resourceId.');
  if (!threadId) throw new Error('Knowledge tools require an active threadId.');
  return [`org:${organizationId}`, `resource:${resourceId}`, `thread:${threadId}`];
}

async function getKnowledgeStore(memory: KnowledgeToolsMemory): Promise<KnowledgeStorage> {
  const store = await memory.storage.getStore('knowledge');
  if (!store) throw new Error('Knowledge tools require a configured knowledge storage domain.');
  return store;
}

function normalizeLimit(limit: number | undefined): number {
  return Math.min(Math.max(limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
}

function serializeRecord(record: KnowledgeRecord) {
  return {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Populate requestContext with a non-empty organizationId before invoking the agent/tools, e.g. requestContext.set('organizationId', orgId).
2. Ensure the framework passes the same requestContext into memory/knowledge tool execution (agent.run/stream options).
3. In tests, construct a RequestContext with organizationId set, matching production middleware.

Example fix

// before
await agent.stream(prompt); // no request context
// after
const requestContext = new RequestContext();
requestContext.set('organizationId', 'org_123');
await agent.stream(prompt, { requestContext });

const orgId = requestContext?.get('organizationId');
if (typeof orgId !== 'string' || !orgId.trim()) {
  throw new Error('knowledge tools invoked without organizationId');
}

function hasKnowledgeScope(ctx?: { requestContext?: { get(k: string): unknown } }): boolean {
  const org = ctx?.requestContext?.get('organizationId');
  return typeof org === 'string' && org.trim().length > 0;
}

try {
  await knowledgeTool.invoke({ requestContext, agent });
} catch (e) {
  if (e instanceof Error && e.message === 'Knowledge tools require requestContext.organizationId.') {
    requestContext.set('organizationId', resolveOrgFromAuth());
    // retry once with context populated
  } else throw e;
}

When it happens

Trigger: Invoking a knowledge tool (via agent tool call or direct call) where context.requestContext is undefined, or requestContext.get('organizationId') returns undefined/non-string/whitespace-only.

Common situations: Calling the memory/agent API outside a request lifecycle without building a requestContext; forgetting to set organizationId in middleware; multi-tenant setups where org id propagation was recently added; unit tests invoking tools without a request context.

Related errors

• Subconscious requires requestContext.organizationId to deriv
• Knowledge tools require an active resourceId.
• No model available: this run started without a controller se
• Project path is required
• Subconscious requires resourceId to derive scoped knowledge.

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