Cannot expand knowledge scope to ${level}: context has no ${

Error message

Cannot expand knowledge scope to ${level}: context has no ${level} entry

What it means

expandKnowledgeScope(context, level) narrows a canonical context scope down to entries at or above the requested level, but it requires the context to actually contain an entry at that target level ('<level>:...'). If after filtering no entry starts with 'level:', it throws — you cannot expand a scope to a level the context never included.

Source

Thrown at packages/core/src/storage/domains/knowledge/base.ts:328

}

export function knowledgeScopeKey(scope: KnowledgeScope): string {
  return canonicalizeKnowledgeScope(scope).join('\u001f');
}

export function isKnowledgeScopeVisible(recordScope: KnowledgeScope, queryScope: KnowledgeScope): boolean {
  const available = new Set(queryScope);
  return recordScope.every(entry => available.has(entry));
}

export function expandKnowledgeScope(context: KnowledgeScope, level: KnowledgeScopeLevel): KnowledgeScope {
  const maxOrder = SCOPE_ORDER[level];
  const expanded = canonicalizeKnowledgeScope(context).filter(entry => {
    const namespace = entry.slice(0, entry.indexOf(':')) as KnowledgeScopeLevel;
    return (SCOPE_ORDER[namespace] ?? Number.MAX_SAFE_INTEGER) <= maxOrder;
  });
  if (!expanded.some(entry => entry.startsWith(`${level}:`))) {
    throw new Error(`Cannot expand knowledge scope to ${level}: context has no ${level} entry`);
  }
  return expanded;
}

/**
 * Maximum length of {@link KnowledgeNode.description}, counted in UTF-16 code units.
 *
 * `description` is a concise synopsis rendered into graph and list payloads, potentially across
 * hundreds of nodes at once, so the bound belongs to the storage contract rather than to any one
 * writer: every adapter enforces it in `createNode` and `updateNode` regardless of which tool
 * performs the write. Long-form detail stays in {@link KnowledgeNode.content}.
 *
 * @experimental
 */
export const MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH = 400;

/**
 * Rejects an over-long node description before any write occurs, so an oversized update leaves the

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure the context scope contains the target level entry before calling expandKnowledgeScope.
Choose the narrowest level actually present in your context instead of hard-coding 'thread'.
For thread-less operations, expand to 'org' or 'resource' so nodeScope/guidanceScope still resolve.
Check the error text: it names the exact missing level; add the corresponding '<level>:<id>' entry.

Example fix

// before
const scope = expandKnowledgeScope([`org:${orgId}`], 'thread');
// after
const context = [`org:${orgId}`, `resource:${resourceId}`, `thread:${threadId}`];
const scope = expandKnowledgeScope(context, 'thread');

Defensive patterns

Strategy: validation

Validate before calling

function canExpandTo(context: string[], level: 'org' | 'resource' | 'thread'): boolean {
  return context.some(e => e.startsWith(`${level}:`));
}
// prefer the narrowest level actually present:
const level = canExpandTo(ctx, 'thread') ? 'thread' : canExpandTo(ctx, 'resource') ? 'resource' : 'org';

Try / catch

try {
  scope = expandKnowledgeScope(context, 'thread');
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Cannot expand knowledge scope to')) {
    scope = expandKnowledgeScope(context, 'resource'); // or 'org' fallback
  } else throw e;
}

Prevention

Check the context contains the target level before expanding.
Use fallback levels for thread-less contexts (jobs, global agents).
Spell levels exactly: 'org' | 'resource' | 'thread' (no plurals).

When it happens

Trigger: expandKnowledgeScope(['org:o1'], 'thread') (no thread entry); expandKnowledgeScope(['org:o1', 'resource:r1'], 'thread'); calling with a context whose thread/resource entries were filtered out by the level cut itself (e.g. level 'resource' but context only has thread entries).

Common situations: Requests outside a thread (background jobs, global agents) trying to resolve thread-scoped knowledge; using a resolution context that omitted ancestor entries; mixing up argument order or level names ('threads' vs 'thread').

Related errors

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