{"record":{"id":"f997750a1f96d0bb","repo":"mastra-ai/mastra","slug":"cannot-expand-knowledge-scope-to-level-context","errorCode":null,"errorMessage":"Cannot expand knowledge scope to ${level}: context has no ${level} entry","messagePattern":"Cannot expand knowledge scope to (.+?): context has no (.+?) entry","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/knowledge/base.ts","lineNumber":328,"sourceCode":"}\n\nexport function knowledgeScopeKey(scope: KnowledgeScope): string {\n  return canonicalizeKnowledgeScope(scope).join('\\u001f');\n}\n\nexport function isKnowledgeScopeVisible(recordScope: KnowledgeScope, queryScope: KnowledgeScope): boolean {\n  const available = new Set(queryScope);\n  return recordScope.every(entry => available.has(entry));\n}\n\nexport function expandKnowledgeScope(context: KnowledgeScope, level: KnowledgeScopeLevel): KnowledgeScope {\n  const maxOrder = SCOPE_ORDER[level];\n  const expanded = canonicalizeKnowledgeScope(context).filter(entry => {\n    const namespace = entry.slice(0, entry.indexOf(':')) as KnowledgeScopeLevel;\n    return (SCOPE_ORDER[namespace] ?? Number.MAX_SAFE_INTEGER) <= maxOrder;\n  });\n  if (!expanded.some(entry => entry.startsWith(`${level}:`))) {\n    throw new Error(`Cannot expand knowledge scope to ${level}: context has no ${level} entry`);\n  }\n  return expanded;\n}\n\n/**\n * Maximum length of {@link KnowledgeNode.description}, counted in UTF-16 code units.\n *\n * `description` is a concise synopsis rendered into graph and list payloads, potentially across\n * hundreds of nodes at once, so the bound belongs to the storage contract rather than to any one\n * writer: every adapter enforces it in `createNode` and `updateNode` regardless of which tool\n * performs the write. Long-form detail stays in {@link KnowledgeNode.content}.\n *\n * @experimental\n */\nexport const MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH = 400;\n\n/**\n * Rejects an over-long node description before any write occurs, so an oversized update leaves the","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/knowledge/base.ts#L310-L346","documentation":"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.","triggerScenarios":"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).","commonSituations":"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').","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."],"exampleFix":"// before\nconst scope = expandKnowledgeScope([`org:${orgId}`], 'thread');\n// after\nconst context = [`org:${orgId}`, `resource:${resourceId}`, `thread:${threadId}`];\nconst scope = expandKnowledgeScope(context, 'thread');","handlingStrategy":"validation","validationCode":"function canExpandTo(context: string[], level: 'org' | 'resource' | 'thread'): boolean {\n  return context.some(e => e.startsWith(`${level}:`));\n}\n// prefer the narrowest level actually present:\nconst level = canExpandTo(ctx, 'thread') ? 'thread' : canExpandTo(ctx, 'resource') ? 'resource' : 'org';","typeGuard":null,"tryCatchPattern":"try {\n  scope = expandKnowledgeScope(context, 'thread');\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Cannot expand knowledge scope to')) {\n    scope = expandKnowledgeScope(context, 'resource'); // or 'org' fallback\n  } else throw e;\n}","preventionTips":["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)."],"tags":["knowledge","scope","hierarchy","validation"],"backgroundTag":"invalid-scope-entry","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}