mastra-ai/mastra · error · WorkspaceNotAvailableError

NO_WORKSPACE

NO_WORKSPACE

Error message

Workspace not available. Ensure the agent has a workspace configured.

What it means

Thrown by requireWorkspace when tool execution context has no workspace. Every workspace tool calls this first; without a workspace there is no filesystem/sandbox to act on. WorkspaceNotAvailableError carries code NO_WORKSPACE.

Source

Thrown at packages/core/src/workspace/tools/helpers.ts:38

 * strings (e.g. `"10"` instead of `10`), and a strict `z.number()` rejects
 * the call outright. Coerce unambiguous numeric strings; anything else
 * passes through unchanged so schema validation still reports it.
 */
export function coerceNumericString(value: unknown): unknown {
  if (typeof value !== 'string') {
    return value;
  }
  const trimmed = value.trim();
  return NUMERIC_STRING_REGEX.test(trimmed) ? Number(trimmed) : value;
}

/**
 * Extract workspace from tool execution context.
 * Throws if workspace is not available.
 */
export function requireWorkspace(context: ToolExecutionContext): Workspace {
  if (!context?.workspace) {
    throw new WorkspaceNotAvailableError();
  }
  return context.workspace;
}

/**
 * Extract filesystem from workspace in tool execution context.
 * Throws if workspace or filesystem is not available.
 */
export function requireFilesystem(context: ToolExecutionContext): {
  workspace: Workspace;
  filesystem: WorkspaceFilesystem;
} {
  const workspace = requireWorkspace(context);
  if (!workspace.filesystem) {
    throw new FilesystemNotAvailableError();
  }
  return { workspace, filesystem: workspace.filesystem };
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a workspace when creating the agent: `new Agent({ name, model, workspace })`
2. If invoking the tool directly, include `workspace` in the execution context
3. Verify the agent pipeline/version actually injects workspace into tool context
4. Catch NO_WORKSPACE and return a clear setup message to the caller

Example fix

// before
const agent = new Agent({ name: 'a', model: 'openai/gpt-4o' });
// after
const agent = new Agent({ name: 'a', model: 'openai/gpt-4o', workspace: myWorkspace });

if (!context?.workspace) {
  throw new Error('Agent must be created with a workspace before using workspace tools');
}

function hasWorkspace(ctx: ToolExecutionContext | undefined): ctx is ToolExecutionContext & { workspace: Workspace } {
  return !!ctx && !!ctx.workspace;
}

try {
  return await tool.execute(ctx);
} catch (e: any) {
  if (e?.code === 'NO_WORKSPACE' || /Workspace not available/i.test(e?.message ?? '')) {
    return { error: 'Configure a workspace on the agent to use this tool.' };
  }
  throw e;
}

When it happens

Trigger: Executing a workspace tool via an agent (or directly) whose ToolExecutionContext lacks `workspace` — e.g. agent created without a workspace option, or tool invoked outside the standard agent pipeline.

Common situations: Forgetting `new Agent({ workspace })` configuration; calling tool.execute manually with a bare context; older integration paths that predate workspace injection.

Related errors

• NO_FILESYSTEM
• NO_SANDBOX
• Auth0 domain and audience are required, please provide them
• Bright Data API token is required. Pass { apiKey } or set BR
• @mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispat

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