mastra-ai/mastra · error · HTTPException

Not found

Error message

Not found

What it means

Workspace route error handler that converts filesystem 'not found' errors into HTTP 404 with the underlying error message (or the fallback 'Not found'). Raised by workspace list/get and workspace filesystem read/write/list/delete routes when the target workspace or file path does not exist.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:124

function isFilesystemPermissionError(error: unknown): boolean {
  if (!error || typeof error !== 'object') return false;

  if ('code' in error && error.code === 'EACCES') return true;

  if ('name' in error && error.name === 'PermissionError') return true;

  return false;
}

/**
 * Workspace-specific error handler.
 * Converts filesystem errors to appropriate HTTP status codes,
 * then falls back to generic handler.
 */
function handleWorkspaceError(error: unknown, defaultMessage: string): never {
  if (isFilesystemNotFoundError(error)) {
    const message = error instanceof Error ? error.message : 'Not found';
    throw new HTTPException(404, { message });
  }
  if (isFilesystemPermissionError(error)) {
    const message = error instanceof Error ? error.message : 'Permission denied';
    throw new HTTPException(403, { message });
  }
  return handleError(error, defaultMessage);
}

/**
 * Throws if workspace v1 is not supported by the current version of @mastra/core.
 */
function requireWorkspaceV1Support(): void {
  if (!coreFeatures.has('workspaces-v1')) {
    throw new HTTPException(501, {
      message: 'Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.',
    });
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the workspace ID via the list-workspaces endpoint before filesystem operations
2. Check the exact file path (case-sensitive) exists within the workspace
3. Create the file/directory first if the operation assumes prior existence

Example fix

// before
await client.workspace(wsId).file('data/config.json').read(); // file absent
// after
await client.workspace(wsId).file('data/config.json').write('{}');
const cfg = await client.workspace(wsId).file('data/config.json').read();

const ws = await client.listWorkspaces(); if (!ws.some(w => w.id === workspaceId)) throw new Error(`Workspace ${workspaceId} does not exist`);

const workspaceExists = async (id: string) => (await client.listWorkspaces()).some(w => w.id === id);

try { await workspaceFs.read(path); } catch (e) { if (isHttpException(e, 404)) console.warn('Workspace/path not found:', path); else throw e; }

When it happens

Trigger: GET a workspace ID that is not registered; reading/writing/deleting a file path under the workspace that does not exist; listing a workspace directory that was removed.

Common situations: Stale workspace IDs cached in clients after deletion; typos in file paths (paths outside the workspace root); assuming files exist before first write.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Plan file "${path}" not found
• No workspace filesystem configured
• CompositeFilesystem requires at least one mount
• Nested mount paths are not supported: "${b}" is nested under
• EACCES

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