{"record":{"id":"cb74b67904d3c6e9","repo":"mastra-ai/mastra","slug":"not-visible","errorCode":"not-visible","errorMessage":"Knowledge record is not visible in the selected scope.","messagePattern":"Knowledge record is not visible in the selected scope\\.","errorType":"error_code","errorClass":"KnowledgeInspectorError","httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/knowledge-inspector.ts","lineNumber":496,"sourceCode":"    if (level === 'org') return [`org:${binding.ownerId}`];\n    const scope = [`org:${binding.ownerId}`, `resource:${binding.resourceId}`];\n    if (level === 'resource') return scope;\n    if (!binding.threadId) {\n      throw new KnowledgeInspectorError('unavailable', 'The active thread does not belong to this project.');\n    }\n    return [...scope, `thread:${binding.threadId}`];\n  }\n\n  async #assertStable(binding: Binding): Promise<void> {\n    const current = await this.#binding();\n    if (current.identityKey !== binding.identityKey || current.fingerprint !== binding.fingerprint) {\n      throw new KnowledgeInspectorError('stale-handle', 'Knowledge scope changed while the request was running.');\n    }\n  }\n\n  #assertVisible<T extends KnowledgeNode>(record: T | null, scope: KnowledgeScope): asserts record is T {\n    if (!record || !isKnowledgeScopeVisible(record.scope, scope)) {\n      throw new KnowledgeInspectorError('not-visible', 'Knowledge record is not visible in the selected scope.');\n    }\n  }\n\n  #recordSummary(\n    record: KnowledgeNode,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n  ): KnowledgeInspectorNodeSummary {\n    const type: KnowledgeInspectorRecordType = 'node';\n    return {\n      handle: this.#mintHandle(binding, level, type, record.id),\n      type,\n      name: record.name,\n      kind: record.kind,\n      scope: scopeBadge(record.scope),\n      version: record.version,\n      updatedAt: record.updatedAt.toISOString(),\n    };","sourceCodeStart":478,"sourceCodeEnd":514,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/knowledge-inspector.ts#L478-L514","documentation":"#assertVisible() is a narrowing assertion: a record must exist AND its stored scope (org/resource/thread) must be visible within the caller's requested scope, checked via isKnowledgeScopeVisible. If the record is missing or lives outside the selected scope level, it throws KnowledgeInspectorError 'not-visible' — an access-control boundary, not a crash bug.","triggerScenarios":"Resolving a record by id or handle whose scope is broader/narrower than the requested level — e.g. asking for a thread-scoped record while bound to 'resource' level, or the record was deleted (null) so the assertion fails.","commonSituations":"Using a handle minted at one scope level with a request at another; reading a node that exists only in an org-wide scope while inspecting project scope; record deleted between listing and reading.","solutions":["Request a scope level that covers the record (e.g. use 'org' or 'resource' level for records not confined to the thread).","Only use handles/cursors within the scope level they were minted at.","Catch KnowledgeInspectorError 'not-visible' and treat it as an empty/filtered result rather than retrying."],"exampleFix":"// before\nconst node = await inspector.getNode(handle, { level: 'thread' }); // record is resource-scoped\n// after\nconst node = await inspector.getNode(handle, { level: 'resource' }); // scope covers record","handlingStrategy":"type-guard","validationCode":"function scopeCovers(level: 'org' | 'resource' | 'thread', recordScope: string[]): boolean {\n  if (level === 'org') return true;\n  if (level === 'resource') return recordScope.some(s => s.startsWith('resource:'));\n  return recordScope.some(s => s.startsWith('thread:'));\n}\n// check before requesting a record at a given level","typeGuard":"function isVisibleRecord<T extends { scope: string[] }>(record: T | null | undefined, scope: string[]): record is T {\n  return record != null && record.scope.every(tag => scope.includes(tag) || scope.some(s => s.startsWith('org:') && tag.startsWith('org:')));\n}","tryCatchPattern":"try {\n  const node = await inspector.getNode(handle, { level });\n} catch (e) {\n  if (e instanceof KnowledgeInspectorError && e.code === 'not-visible') {\n    return undefined; // treat as filtered-out, not an error\n  }\n  throw e;\n}","preventionTips":["Only present records to users whose scope level matches how they were listed.","Never reuse handles across different scope levels.","Handle deleted records: treat not-visible as 'gone or restricted'."],"tags":["knowledge-inspector","access-control","scope"],"backgroundTag":"record-not-visible-in-scope","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}