{"record":{"id":"1aadaadc46f6baca","repo":"mastra-ai/mastra","slug":"path-decodedpath-not-found","errorCode":null,"errorMessage":"Path \"${decodedPath}\" not found","messagePattern":"Path \"(.+?)\" not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":498,"sourceCode":"  tags: ['Workspace'],\n  handler: async ({ mastra, path, encoding, workspaceId }) => {\n    try {\n      requireWorkspaceV1Support();\n\n      if (!path) {\n        throw new HTTPException(400, { message: 'Path is required' });\n      }\n\n      const workspace = await getWorkspaceById(mastra, workspaceId);\n      if (!workspace?.filesystem) {\n        throw new HTTPException(404, { message: 'No workspace filesystem configured' });\n      }\n\n      const decodedPath = decodeURIComponent(path);\n\n      // Check if path exists\n      if (!(await workspace.filesystem.exists(decodedPath))) {\n        throw new HTTPException(404, { message: `Path \"${decodedPath}\" not found` });\n      }\n\n      // Read file content\n      const content = await workspace.filesystem.readFile(decodedPath, {\n        encoding: (encoding as BufferEncoding) || 'utf-8',\n      });\n\n      return {\n        path: decodedPath,\n        content: typeof content === 'string' ? content : content.toString('utf-8'),\n        type: 'file' as const,\n      };\n    } catch (error) {\n      return handleWorkspaceError(error, 'Error reading file');\n    }\n  },\n});\n","sourceCodeStart":480,"sourceCodeEnd":516,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L480-L516","documentation":"Thrown (HTTP 404) by the workspace file read handler when the decoded path does not exist in the workspace filesystem, as determined by filesystem.exists() before reading. This is the standard 'file not found' error for workspace file reads, reported with the exact decoded path to aid debugging.","triggerScenarios":"GET file read with a path that doesn't exist — typos, wrong case on case-sensitive mounts, path relative to the wrong root, reading a file before it's written, or double-encoding issues where the decoded path isn't the intended one.","commonSituations":"Race with a workflow that hasn't produced the file yet; referencing files outside the workspace root (paths are workspace-relative, not host-absolute); Git checkout differences deleting generated artifacts.","solutions":["Confirm the file exists relative to the workspace filesystem root; list the directory via the workspace list endpoint to see actual entries.","Fix path casing/spelling — mounts are typically case-sensitive.","If the file is generated, ensure the producing step/workflow completed before reading.","Check for double URL-encoding: pass the path encoded once with encodeURIComponent."],"exampleFix":"// before\nconst p = '/absolute/host/path/output.json';\n// after (workspace-relative path that exists)\nconst p = 'output.json';","handlingStrategy":"validation","validationCode":"const entries = await listWorkspaceDir({ workspaceId, path: dirname(p) });\nif (!entries.some(e => e.path === p)) {\n  throw new Error(`File \"${p}\" does not exist in workspace ${workspaceId}`);\n}","typeGuard":"function fileExistsIn(entries: { path: string }[], p: string): boolean {\n  return entries.some(e => e.path === p || e.path === p.replace(/^\\//, ''));\n}","tryCatchPattern":"try {\n  return await readWorkspaceFile({ workspaceId, path: p });\n} catch (e) {\n  if (isHttpException(e, 404) && e.message.includes('not found')) {\n    const listing = await listWorkspaceDir({ workspaceId, path: dirname(p) });\n    throw new Error(`File \"${p}\" not found. Nearby entries: ${listing.map(e => e.path).join(', ')}`);\n  }\n  throw e;\n}","preventionTips":["Use the workspace list endpoint to verify paths before reading.","Remember paths are workspace-relative, never host-absolute.","Match casing exactly — mounts are case-sensitive.","Synchronize reads with the workflow/step that creates the file."],"tags":["workspace","http-404","file-not-found","path"],"backgroundTag":"file-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}