mastra-ai/mastra · error · Error

Knowledge write tools require a configured knowledge storage

Error message

Knowledge write tools require a configured knowledge storage domain.

What it means

The knowledge write tools (knowledge_append, knowledge_remove, knowledge_update_node, knowledge_merge_nodes, knowledge_rescope, knowledge_write_node_*) all fetch the 'knowledge' storage domain via memory.storage.getStore('knowledge') before performing any mutation. When that named store is not configured, getStore throws this write-tool variant of the missing-storage-domain error to protect against unbacked mutations.

Source

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

const MAX_GUIDANCE_LENGTH = 4_000;
const scopeLevelSchema: JSONSchema7 = { type: 'string', enum: ['org', 'resource', 'thread'] };

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

export interface KnowledgeWriteToolsOptions {
  scope: KnowledgeScope;
  sourceThreadId: string;
  defaultScope: KnowledgeScopeLevel;
  maxScope?: KnowledgeScopeLevel;
}

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

function resolveWriteScope(options: KnowledgeWriteToolsOptions, level?: KnowledgeScopeLevel): KnowledgeScope {
  const scope = expandKnowledgeScope(options.scope, level ?? options.defaultScope);
  assertKnowledgeScopeWithinCeiling(scope, options.maxScope);
  return scope;
}

function requireVisible(scope: KnowledgeScope, options: KnowledgeWriteToolsOptions, label: string): void {
  if (!isKnowledgeScopeVisible(scope, options.scope)) {
    throw new Error(`${label} is outside the curator's visible scope.`);
  }
}

export function createKnowledgeWriteTools(
  memory: KnowledgeWriteToolsMemory,
  options: KnowledgeWriteToolsOptions,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register and provision the 'knowledge' storage domain on the storage instance passed to createKnowledgeWriteTools.
2. Run storage setup/migrations so getStore('knowledge') returns a store.
3. Use the same storage instance for memory and curator tools — not two differently configured adapters.
4. Pre-flight check: await memory.storage.getStore('knowledge') before enabling curator tools.

Example fix

// before
const curatorTools = createKnowledgeWriteTools({ storage: messageOnlyStorage }, options);
// after
const curatorTools = createKnowledgeWriteTools({ storage: storageWithKnowledgeDomain }, options);

const store = await memory.storage.getStore('knowledge');
if (!store) throw new Error('Curator write tools disabled: knowledge storage domain not configured.');
const tools = createKnowledgeWriteTools(memory, options);

async function isCuratorStorageReady(memory: { storage: { getStore(n: 'knowledge'): Promise<unknown> } }): Promise<boolean> {
  return (await memory.storage.getStore('knowledge')) !== undefined;
}

try {
  return await curatorTools.knowledge_append.execute(args, {} as any);
} catch (e) {
  if (e instanceof Error && e.message.includes('configured knowledge storage domain')) {
    return { success: false, reason: 'knowledge-store-missing' };
  }
  throw e;
}

When it happens

Trigger: Invoking any curator write tool produced by createKnowledgeWriteTools when the memory/storage instance lacks a registered 'knowledge' store.

Common situations: Storage adapter without named-store support; fresh deployments where the knowledge domain was never provisioned; pointing curator agents at a storage instance separate from the one where the knowledge domain is configured.

Related errors

• Knowledge tools require a configured knowledge storage domai
• Knowledge tools require an active threadId.
• ${label} is outside the curator's visible scope.

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