{"record":{"id":"7dc1ffc859dcdae0","repo":"mastra-ai/mastra","slug":"knowledge-scope-cannot-be-empty","errorCode":null,"errorMessage":"Knowledge scope cannot be empty","messagePattern":"Knowledge scope cannot be empty","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/knowledge/base.ts","lineNumber":292,"sourceCode":"let lastUlidRandom = 0n;\n\nexport function canonicalizeKnowledgeScope(scope: KnowledgeScope): KnowledgeScope {\n  const entriesByLevel = new Map<KnowledgeScopeLevel, string>();\n  for (const entry of scope) {\n    const separator = entry.indexOf(':');\n    const level = entry.slice(0, separator) as KnowledgeScopeLevel;\n    const id = entry.slice(separator + 1);\n    if (separator <= 0 || !id || id.includes('\\u001f') || SCOPE_ORDER[level] === undefined) {\n      throw new Error(`Invalid knowledge scope entry: ${entry}`);\n    }\n    const existing = entriesByLevel.get(level);\n    if (existing && existing !== entry) {\n      throw new Error(`Knowledge scope contains multiple ${level} entries`);\n    }\n    entriesByLevel.set(level, entry);\n  }\n  if (entriesByLevel.size === 0) {\n    throw new Error('Knowledge scope cannot be empty');\n  }\n  if (entriesByLevel.has('thread') && (!entriesByLevel.has('resource') || !entriesByLevel.has('org'))) {\n    throw new Error('Thread knowledge scope requires resource and org ancestors');\n  }\n  if (entriesByLevel.has('resource') && !entriesByLevel.has('org')) {\n    throw new Error('Resource knowledge scope requires an org ancestor');\n  }\n\n  const unique = [...new Set(scope)];\n  unique.sort((a, b) => {\n    const aLevel = a.slice(0, a.indexOf(':')) as KnowledgeScopeLevel;\n    const bLevel = b.slice(0, b.indexOf(':')) as KnowledgeScopeLevel;\n    const aOrder = SCOPE_ORDER[aLevel] ?? Number.MAX_SAFE_INTEGER;\n    const bOrder = SCOPE_ORDER[bLevel] ?? Number.MAX_SAFE_INTEGER;\n    return aOrder - bOrder || a.localeCompare(b);\n  });\n  return unique;\n}","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/knowledge/base.ts#L274-L310","documentation":"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.","triggerScenarios":"Passing [] (or an array that filtered down to empty) as the scope for createNode, appendKnowledge, listNodes, search, queryScope, or knowledgeScopeKey.","commonSituations":"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 ?? [] .","solutions":["Always include at least an org entry, e.g. ['org:<orgId>'].","Validate the resolved scope is non-empty before invoking knowledge APIs (fail early at config load).","Check your scope-resolution/defaultScope path: an empty defaultScope in AppendKnowledgeInput will surface as this error.","Throw a descriptive application-level error when tenant/org context is missing instead of passing an empty array."],"exampleFix":"// before\nconst scope: KnowledgeScope = [];\n// after\nif (!orgId) throw new Error('Missing org context for knowledge scope');\nconst scope: KnowledgeScope = [`org:${orgId}`];","handlingStrategy":"validation","validationCode":"function requireNonEmptyScope(scope: string[] | undefined): string[] {\n  if (!scope || scope.length === 0) throw new Error('Knowledge operation requires a non-empty scope (at least org:<id>)');\n  return scope;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fail fast at tenant/org context resolution when orgId is missing.","Never use `?? []` as a silent default for scope; surface the missing context instead.","Check that defaultScope in AppendKnowledgeInput is always populated."],"tags":["knowledge","scope","validation","empty-input"],"backgroundTag":"invalid-scope-entry","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}