mastra-ai/mastra · error

Session workspace is not available

Error message

Session workspace is not available

What it means

readSessionWorkspaceFile resolves the session's sandbox (workspace handle) via sessionSandbox(session); if no sandbox exists for the session there is no filesystem to stat/read, so the function throws. This means the session has no live workspace handle at read time.

Source

Thrown at mastracode/factory/src/routes/fs.ts:556

      updatedAt: new Date((Number(mtimeStr) || 0) * 1000).toISOString(),
    });
  }
  entries.sort((a, b) => a.path.localeCompare(b.path));

  return { workspacePath: session.sessionId, root: safeRoot, rootPath, entries };
}

/** Read a file inside a session's sandbox. Paths outside rendered roots require a persisted-file allowlist check in the route. */
export async function readSessionWorkspaceFile(
  session: SourceControlSession,
  path: string,
  options: { allowUnapprovedPath?: boolean } = {},
): Promise<WorkspaceFile> {
  const safePath = assertRelativePath(path, 'path');
  if (!options.allowUnapprovedPath) assertApprovedRenderedRoot(safePath.split('/')[0] ?? '');

  const handle = await sessionSandbox(session);
  if (!handle) throw new Error('Session workspace is not available');
  const { filesystem } = handle;
  const info = await filesystem.stat(safePath);
  if (info.type === 'directory') throw new Error('Path is a directory');

  const buffer = (await filesystem.readFile(safePath)) as Buffer;
  const truncated = buffer.length > MAX_TEXT_FILE_BYTES;
  const base = {
    workspacePath: session.sessionId,
    path: safePath,
    name: posixPath.basename(safePath),
    size: buffer.length,
    updatedAt: info.modifiedAt.toISOString(),
  };
  try {
    const content = TEXT_DECODER.decode(truncated ? buffer.subarray(0, MAX_TEXT_FILE_BYTES) : buffer);
    return { ...base, contentType: 'text', content, truncated };
  } catch {
    return { ...base, contentType: 'unsupported' };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the session's sandbox/workspace is started and attached before attempting file reads.
2. Check sessionSandbox(session) for the target session; if null, reinitialize or recreate the session workspace.
3. If the session is finished, re-open or resume the session so its workspace handle is restored before reading files.
4. Handle the null-handle case in the route and return a clear 404/409 so clients can refetch a fresh session.

Example fix

// before
const file = await readSessionWorkspaceFile(session, 'src/index.ts');
// after
const handle = await sessionSandbox(session);
if (!handle) await resumeSessionWorkspace(session); // provision workspace first
const file = await readSessionWorkspaceFile(session, 'src/index.ts');

const handle = await sessionSandbox(session);
const canRead = Boolean(handle);
if (!canRead) await provisionOrResumeWorkspace(session);

async function workspaceAvailable(session: SourceControlSession): Promise<boolean> {
  return (await sessionSandbox(session)) != null;
}

try {
  const file = await readSessionWorkspaceFile(session, path);
} catch (e) {
  if (e instanceof Error && e.message === 'Session workspace is not available') {
    await resumeSessionWorkspace(session); // recreate the sandbox, then retry once
    const file = await readSessionWorkspaceFile(session, path);
  } else throw e;
}

When it happens

Trigger: Calling readSessionWorkspaceFile (or the file route in buildFsRoutes) for a session whose sandbox has not been created yet or has been torn down (session ended, sandbox reclaimed, or workspace provisioning failed).

Common situations: Reading a file from a stale session after the agent run finished and the sandbox was recycled; querying a session before the workspace was provisioned; environment where sandbox startup failed so handles are never registered.

Related errors

• Invalid encrypted session data
• MastraAuthBetterAuth is not initialized — init() must run fi
• Invalid encrypted session data
• [MastraAuthGoogle] GOOGLE_COOKIE_PASSWORD is required for Go
• Session validation failed

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