{"record":{"id":"256fa8058f7879e1","repo":"mastra-ai/mastra","slug":"session-not-found","errorCode":"session_not_found","errorMessage":"session_not_found","messagePattern":"session_not_found","errorType":"error_code","errorClass":"SkillInvocationError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/skills/service.ts","lineNumber":56,"sourceCode":"\n  constructor(code: SkillInvocationError['code'], message: string) {\n    super(message);\n    this.name = 'SkillInvocationError';\n    this.code = code;\n  }\n}\n\nfunction escapeSkillBoundary(value: string): string {\n  return value.replaceAll('</skill>', '&lt;/skill&gt;');\n}\n\n/** Kicks a run off from a plain prompt, for runs that activate no skill. */\nexport async function resolvePromptInvocation(\n  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,\n  input: { resourceId: string; scope?: SkillInvocationInput['scope']; prompt: string },\n): Promise<{ session: SkillSession; message: string }> {\n  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;\n  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');\n  return { session, message: input.prompt };\n}\n\nexport async function resolveSkillInvocation(\n  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,\n  input: SkillInvocationInput,\n): Promise<{ session: SkillSession; skillName: string; message: string }> {\n  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;\n  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');\n\n  const skills = session.getWorkspace().skills;\n  await skills?.maybeRefresh();\n  const skill = await skills?.get(input.name);\n  if (!skill || skill['user-invocable'] === false) {\n    throw new SkillInvocationError('skill_not_found', `Skill not found: ${input.name}.`);\n  }\n\n  const args = input.arguments?.trim();","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/skills/service.ts#L38-L74","documentation":"resolvePromptInvocation looks up the SkillSession for a resourceId via controller.getSessionByResource. If no session exists for that resource/scope, it throws SkillInvocationError with code 'session_not_found'. The library refuses to start a prompt run without an existing agent session.","triggerScenarios":"Calling resolvePromptInvocation with a resourceId that has no session, or with a scope that does not match the scope the session was created under.","commonSituations":"Resuming a run after the session was deleted or storage was wiped; passing a resourceId from a different workspace/org; scope mismatch (e.g. run scoped to a thread that doesn't exist).","solutions":["Verify the resourceId exists and a session was created for it before invoking","Check that the scope argument matches the session's scope (or omit scope to use the default)","Create/initialize the agent session first via the agent controller","Inspect storage to confirm the session row still exists"],"exampleFix":"// before\nconst run = await resolvePromptInvocation(controller, { resourceId: id, prompt });\n// after\nconst existing = await controller.getSessionByResource(id);\nif (!existing) await createSessionForResource(controller, id);\nconst run = await resolvePromptInvocation(controller, { resourceId: id, prompt });","handlingStrategy":"try-catch","validationCode":"const session = await controller.getSessionByResource(resourceId, scope);\nif (!session) throw new Error(`No session for resourceId=${resourceId}`);","typeGuard":"function hasSession(s: unknown): s is SkillSession {\n  return !!s && typeof (s as SkillSession).getWorkspace === 'function';\n}","tryCatchPattern":"try {\n  await resolvePromptInvocation(controller, input);\n} catch (e) {\n  if (e instanceof SkillInvocationError && e.code === 'session_not_found') {\n    await bootstrapSession(controller, input.resourceId, input.scope);\n  } else throw e;\n}","preventionTips":["Verify the resourceId exists in the current storage before invoking","Omit scope or pass the exact scope the session was created with","Create the session as part of the run bootstrap flow","Never reuse resourceIds across environments"],"tags":["session","not-found","skill-invocation"],"backgroundTag":"session-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}