mastra-ai/mastra · error · Error

Knowledge scope cannot be empty

Error message

Knowledge scope cannot be empty

What it means

Knowledge scopes are hierarchical and must be non-empty: an empty scope array has no anchoring level, so canonicalizeKnowledgeScope rejects it. Every knowledge operation needs at least one scope entry (an org at minimum) to compute visibility and storage keys.

Source

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

let lastUlidRandom = 0n;

export function canonicalizeKnowledgeScope(scope: KnowledgeScope): KnowledgeScope {
  const entriesByLevel = new Map<KnowledgeScopeLevel, string>();
  for (const entry of scope) {
    const separator = entry.indexOf(':');
    const level = entry.slice(0, separator) as KnowledgeScopeLevel;
    const id = entry.slice(separator + 1);
    if (separator <= 0 || !id || id.includes('\u001f') || SCOPE_ORDER[level] === undefined) {
      throw new Error(`Invalid knowledge scope entry: ${entry}`);
    }
    const existing = entriesByLevel.get(level);
    if (existing && existing !== entry) {
      throw new Error(`Knowledge scope contains multiple ${level} entries`);
    }
    entriesByLevel.set(level, entry);
  }
  if (entriesByLevel.size === 0) {
    throw new Error('Knowledge scope cannot be empty');
  }
  if (entriesByLevel.has('thread') && (!entriesByLevel.has('resource') || !entriesByLevel.has('org'))) {
    throw new Error('Thread knowledge scope requires resource and org ancestors');
  }
  if (entriesByLevel.has('resource') && !entriesByLevel.has('org')) {
    throw new Error('Resource knowledge scope requires an org ancestor');
  }

  const unique = [...new Set(scope)];
  unique.sort((a, b) => {
    const aLevel = a.slice(0, a.indexOf(':')) as KnowledgeScopeLevel;
    const bLevel = b.slice(0, b.indexOf(':')) as KnowledgeScopeLevel;
    const aOrder = SCOPE_ORDER[aLevel] ?? Number.MAX_SAFE_INTEGER;
    const bOrder = SCOPE_ORDER[bLevel] ?? Number.MAX_SAFE_INTEGER;
    return aOrder - bOrder || a.localeCompare(b);
  });
  return unique;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always include at least an org entry, e.g. ['org:<orgId>'].
2. Validate the resolved scope is non-empty before invoking knowledge APIs (fail early at config load).
3. Check your scope-resolution/defaultScope path: an empty defaultScope in AppendKnowledgeInput will surface as this error.
4. Throw a descriptive application-level error when tenant/org context is missing instead of passing an empty array.

Example fix

// before
const scope: KnowledgeScope = [];
// after
if (!orgId) throw new Error('Missing org context for knowledge scope');
const scope: KnowledgeScope = [`org:${orgId}`];

function requireNonEmptyScope(scope: string[] | undefined): string[] {
  if (!scope || scope.length === 0) throw new Error('Knowledge operation requires a non-empty scope (at least org:<id>)');
  return scope;
}

When it happens

Trigger: Passing [] (or an array that filtered down to empty) as the scope for createNode, appendKnowledge, listNodes, search, queryScope, or knowledgeScopeKey.

Common situations: Conditional scope construction like scope.push(...) that never ran because config was missing; a filter step that removed invalid entries; default scope resolution returning [] when tenant context is absent; spreading an undefined variable with ?? [] .

Related errors

• Invalid knowledge scope entry: ${entry}
• Knowledge scope contains multiple ${level} entries
• Thread knowledge scope requires resource and org ancestors
• Resource knowledge scope requires an org ancestor
• Cannot expand knowledge scope to ${level}: context has no ${

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