mastra-ai/mastra · error · Error

Knowledge tools require an active resourceId.

Error message

Knowledge tools require an active resourceId.

What it means

After validating organizationId, resolveScope needs a resourceId identifying whose memories/knowledge are accessed. It is resolved from requestContext (via resolveKnowledgeResourceId) falling back to context.agent.resourceId; if neither yields a truthy value, knowledge tools cannot scope access and throw.

Source

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

  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 {
    id: record.id,
    text: record.text,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set resourceId on the agent's memory configuration or pass it in run options so context.agent.resourceId is populated.
2. Set the resource id on requestContext (the key read by resolveKnowledgeResourceId) before tool execution.
3. Inspect resolveKnowledgeResourceId's expected requestContext key and provide it in your middleware.

Example fix

// before
new Agent({ memory: new Memory({ storage }) }); // no resourceId
// after
const memory = new Memory({ storage, options: { resourceId: thread.userId } });
await agent.stream(prompt, { resourceId: thread.userId, threadId: thread.id, requestContext });

const resourceId = requestContext?.get('knowledgeResourceId') ?? agent.resourceId;
if (!resourceId) throw new Error('knowledge tools invoked without resourceId');

function hasKnowledgeResource(ctx?: { requestContext?: { get(k: string): unknown }; agent?: { resourceId?: string; threadId?: string } }): boolean {
  return !!(ctx?.requestContext?.get('knowledgeResourceId') ?? ctx?.agent?.resourceId);
}

try {
  await knowledgeTool.invoke({ requestContext, agent });
} catch (e) {
  if (e instanceof Error && e.message === 'Knowledge tools require an active resourceId.') {
    console.error('Agent run missing resourceId; check memory config / run options');
  } else throw e;
}

When it happens

Trigger: Invoking a knowledge tool where resolveKnowledgeResourceId returns undefined/empty and context.agent.resourceId is unset — e.g. agent run without a resourceId, or requestContext lacking the knowledge resource id key.

Common situations: Agent instantiated without resourceId in memory configuration; server calls that omit per-user resourceId; tests constructing an agent without memory resource setup; renamed config keys after an upgrade.

Related errors

• Knowledge tools require requestContext.organizationId.
• No model available: this run started without a controller se
• Project path is required
• sendStateSignal requires Mastra memory
• Storage is not configured on this AgentController

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