mastra-ai/mastra · error

Merged knowledge node is not visible from scope: ${input.nam

Error message

Merged knowledge node is not visible from scope: ${input.name}

What it means

createNode found an existing knowledge node registered under the same name+scope key, and that node has been merged (mergedInto set) into another node. The merged terminal node's scope is not visible from the scope the caller is creating in, so instead of silently returning the terminal node the store refuses the operation. This prevents resolving a merge through a scope the caller cannot see.

Source

Thrown at packages/core/src/storage/domains/knowledge/inmemory.ts:110

    this.#db.knowledgeCursors.clear();
    this.#db.knowledgeActivity.length = 0;
    this.#db.knowledgeSemanticOutbox.clear();
    this.#db.knowledgeSemanticIdempotency.clear();
  }

  async createNode(input: CreateKnowledgeNodeInput): Promise<KnowledgeNode> {
    return this.#runAtomicMutation(() => this.#createNode(input));
  }

  #createNode(input: CreateKnowledgeNodeInput): KnowledgeNode {
    assertKnowledgeDescriptionWithinBound(input.description);
    const scope = canonicalizeKnowledgeScope(input.scope);
    const key = recordKey(input.name, scope);
    const existingId = this.#db.knowledgeNodeKeys.get(key);
    if (existingId) {
      const terminal = this.#resolveTerminalNode(existingId)!;
      if (!isKnowledgeScopeVisible(terminal.scope, scope)) {
        throw new Error(`Merged knowledge node is not visible from scope: ${input.name}`);
      }
      return cloneNode(terminal);
    }

    const now = new Date();
    const node: KnowledgeNode = {
      id: input.id ?? crypto.randomUUID(),
      type: 'node',
      name: input.name.trim(),
      kind: input.kind,
      content: input.content,
      description: input.description,
      scope,
      version: 1,
      createdAt: now,
      updatedAt: now,
    };
    if (this.#db.knowledgeNodes.has(node.id)) throw new Error(`Knowledge node already exists: ${node.id}`);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fetch the merge chain (getNode on the existing id) to find the terminal node and reference it directly instead of creating a new node with the same name
2. Create the node under a different name or in a scope where the merged terminal node is visible
3. Un-merge or re-merge the target so its scope is visible from the creation scope (merge into a node whose scope is broader or equal)
4. If the key is stale/corrupt, delete the knowledge record so the key is freed before recreating

Example fix

// before
await store.createNode({ name: 'billing-policy', scope, ... });
// after
const existing = store.findNodesByName?.('billing-policy') ?? [];
const node = existing.length
  ? await store.getNode({ id: existing[0].id, resolutionScope: scope })
  : await store.createNode({ name: 'billing-policy', scope, ... });

const existingId = db.knowledgeNodeKeys.get(recordKey(name, canonicalizeKnowledgeScope(scope)));
if (existingId) {
  const terminal = resolveTerminal(existingId);
  if (!isKnowledgeScopeVisible(terminal.scope, scope)) throw new Error(`skip: merged node '${name}' not visible from scope`);
}

function isMergedNodeVisible(terminal: { scope: KnowledgeScope }, scope: KnowledgeScope): boolean {
  return isKnowledgeScopeVisible(terminal.scope, scope);
}

try {
  node = await store.createNode({ name, scope });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Merged knowledge node is not visible from scope')) {
    node = await resolveByNameOrCreateWithSuffix(name, scope);
  } else throw e;
}

When it happens

Trigger: Calling createNode() with a name whose (name, scope) key maps to a node id whose terminal (post-merge-resolution) node has a scope that isKnowledgeScopeVisible() evaluates as not visible from the requested input.scope. Happens when the original node was merged into a node with a narrower or otherwise non-visible scope.

Common situations: Re-creating a node name after it was merged into a node scoped more narrowly (e.g. merged into a resource-scoped node while creating at tenant scope); cross-tenant/workflow merges that changed scope visibility; stale client code assuming the old node still exists at its original scope.

Related errors

• Knowledge node already exists: ${node.id}
• Knowledge node not found: ${id}
• Item ${id} does not belong to dataset ${datasetId}
• Dataset not found: ${datasetId}
• Dataset not found: ${input.datasetId}

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