mastra-ai/mastra · error · SkillInvocationError

session_not_found

session_not_found

Error message

session_not_found

What it means

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.

Source

Thrown at mastracode/factory/src/skills/service.ts:56

  constructor(code: SkillInvocationError['code'], message: string) {
    super(message);
    this.name = 'SkillInvocationError';
    this.code = code;
  }
}

function escapeSkillBoundary(value: string): string {
  return value.replaceAll('</skill>', '&lt;/skill&gt;');
}

/** Kicks a run off from a plain prompt, for runs that activate no skill. */
export async function resolvePromptInvocation(
  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,
  input: { resourceId: string; scope?: SkillInvocationInput['scope']; prompt: string },
): Promise<{ session: SkillSession; message: string }> {
  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;
  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');
  return { session, message: input.prompt };
}

export async function resolveSkillInvocation(
  controller: Pick<AgentController<MastraCodeState>, 'getSessionByResource'>,
  input: SkillInvocationInput,
): Promise<{ session: SkillSession; skillName: string; message: string }> {
  const session = (await controller.getSessionByResource(input.resourceId, input.scope)) as SkillSession | undefined;
  if (!session) throw new SkillInvocationError('session_not_found', 'Agent controller session not found.');

  const skills = session.getWorkspace().skills;
  await skills?.maybeRefresh();
  const skill = await skills?.get(input.name);
  if (!skill || skill['user-invocable'] === false) {
    throw new SkillInvocationError('skill_not_found', `Skill not found: ${input.name}.`);
  }

  const args = input.arguments?.trim();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the resourceId exists and a session was created for it before invoking
2. Check that the scope argument matches the session's scope (or omit scope to use the default)
3. Create/initialize the agent session first via the agent controller
4. Inspect storage to confirm the session row still exists

Example fix

// before
const run = await resolvePromptInvocation(controller, { resourceId: id, prompt });
// after
const existing = await controller.getSessionByResource(id);
if (!existing) await createSessionForResource(controller, id);
const run = await resolvePromptInvocation(controller, { resourceId: id, prompt });

const session = await controller.getSessionByResource(resourceId, scope);
if (!session) throw new Error(`No session for resourceId=${resourceId}`);

function hasSession(s: unknown): s is SkillSession {
  return !!s && typeof (s as SkillSession).getWorkspace === 'function';
}

try {
  await resolvePromptInvocation(controller, input);
} catch (e) {
  if (e instanceof SkillInvocationError && e.code === 'session_not_found') {
    await bootstrapSession(controller, input.resourceId, input.scope);
  } else throw e;
}

When it happens

Trigger: Calling resolvePromptInvocation with a resourceId that has no session, or with a scope that does not match the scope the session was created under.

Common situations: 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).

Related errors

• Project repository not found for this organization.
• Factory session not found
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo

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