mastra-ai/mastra · error

Knowledge scope exceeds ${maxScope} ceiling

Error message

Knowledge scope exceeds ${maxScope} ceiling

What it means

assertKnowledgeScopeWithinCeiling enforces a record's maxScope ceiling: the narrowest level reserved in the record's scope must not be narrower than the ceiling (scope levels are ordered org=0 < resource=1 < thread=2). If the scope reserves a level narrower than the allowed ceiling, the scope 'exceeds' the ceiling and the write/rescope is rejected. This keeps records from being pinned more narrowly than their visibility policy permits.

Source

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

 * @experimental
 */
export function assertKnowledgeDescriptionWithinBound(description: string | undefined): void {
  if (description === undefined) return;
  if (description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {
    throw new Error(
      `Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code unit limit`,
    );
  }
}

export function assertKnowledgeScopeWithinCeiling(scope: KnowledgeScope, maxScope?: KnowledgeScopeLevel): void {
  if (!maxScope) return;
  const reservedLevels = scope
    .map(entry => SCOPE_ORDER[entry.slice(0, entry.indexOf(':')) as KnowledgeScopeLevel])
    .filter((value): value is number => value !== undefined);
  const narrowestLevel = reservedLevels.length > 0 ? Math.max(...reservedLevels) : Number.MAX_SAFE_INTEGER;
  if (narrowestLevel < SCOPE_ORDER[maxScope]) {
    throw new Error(`Knowledge scope exceeds ${maxScope} ceiling`);
  }
}

export function assertKnowledgeCeilingRaised(
  currentMaxScope: KnowledgeScopeLevel | undefined,
  maxScope: KnowledgeScopeLevel | undefined,
): void {
  if (currentMaxScope && maxScope && SCOPE_ORDER[maxScope] > SCOPE_ORDER[currentMaxScope]) {
    throw new Error(`Knowledge ceiling cannot be lowered from ${currentMaxScope} to ${maxScope}`);
  }
}

export function parseKnowledgeWikilinks(text: string): string[] {
  const names: string[] = [];
  const seen = new Set<string>();
  let contentStart = -1;

  for (let index = 0; index < text.length - 1; index++) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Raise the record's ceiling first via raiseKnowledgeCeiling({ id, maxScope: 'thread' }), then rescope/append with the narrower scope.
2. Or keep the record's scope at or above its existing maxScope level (don't add thread entries when maxScope is 'resource').
3. Pass the intended maxScope consistently in AppendKnowledgeInput so scope and ceiling match at creation time.
4. Pre-check with SCOPE_ORDER semantics: narrowest scope level must be >= SCOPE_ORDER[maxScope].

Example fix

// before
await storage.rescopeKnowledge({ id, scope: [`org:o`, `resource:r`, `thread:t`] }); // maxScope 'resource'
// after
await storage.raiseKnowledgeCeiling({ id, maxScope: 'thread' });
await storage.rescopeKnowledge({ id, scope: [`org:o`, `resource:r`, `thread:t`] });

const ORDER = { org: 0, resource: 1, thread: 2 } as const;
function scopeWithinCeiling(scope: string[], maxScope?: keyof typeof ORDER): boolean {
  if (!maxScope) return true;
  const levels = scope.map(e => ORDER[e.slice(0, e.indexOf(':')) as keyof typeof ORDER]).filter((n): n is number => n !== undefined);
  const narrowest = levels.length ? Math.max(...levels) : Number.MAX_SAFE_INTEGER;
  return narrowest >= ORDER[maxScope];
}

try {
  await storage.rescopeKnowledge({ id, scope });
} catch (e) {
  if (e instanceof Error && e.message.includes('ceiling')) {
    await storage.raiseKnowledgeCeiling({ id, maxScope: 'thread' });
    await storage.rescopeKnowledge({ id, scope });
  } else throw e;
}

When it happens

Trigger: appendKnowledge with maxScope:'resource' but scope containing 'thread:<id>'; rescopeKnowledge moving a record into a thread-level scope while its maxScope is 'org' or 'resource'; createKnowledgeWriteTools resolving a write scope narrower than the ceiling passed in input.

Common situations: Widening/narrowing a record via rescopeKnowledge without raising the ceiling first; an agent tool writing thread-scoped notes onto a record created with a stricter ceiling; defaulting maxScope to 'org' while composing thread-level scopes.

Related errors

• Invalid knowledge scope entry: ${entry}
• Knowledge scope contains multiple ${level} entries
• Knowledge scope cannot be empty
• Thread knowledge scope requires resource and org ancestors
• Resource knowledge scope requires an org ancestor

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