{"record":{"id":"139e711f5c20f2c8","repo":"mastra-ai/mastra","slug":"sandbox-workspace-root-resolution-returned-an-empt","errorCode":null,"errorMessage":"Sandbox workspace root resolution returned an empty path","messagePattern":"Sandbox workspace root resolution returned an empty path","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/agents/sandbox-filesystem.ts","lineNumber":123,"sourceCode":"      (typeof options.workdir === 'string'\n        ? `sandbox-fs:${options.sandbox.id}:${options.workdir}`\n        : `sandbox-fs:${options.sandbox.id}`);\n  }\n\n  /** The resolved workspace root; empty until a lazy workdir first resolves. */\n  get basePath(): string {\n    return this.resolvedBase ?? '';\n  }\n\n  /** Await (and memoize) the workspace root, resolving a lazy workdir once. */\n  private async base(): Promise<string> {\n    if (this.resolvedBase) return this.resolvedBase;\n    const source = this.workdirSource;\n    if (typeof source === 'string') return (this.resolvedBase = source);\n    this.resolvingBase ??= Promise.resolve()\n      .then(source)\n      .then(resolved => {\n        if (!resolved) throw new Error('Sandbox workspace root resolution returned an empty path');\n        return (this.resolvedBase = resolved);\n      })\n      .finally(() => {\n        this.resolvingBase = undefined;\n      });\n    return this.resolvingBase;\n  }\n\n  // ── Path handling ──────────────────────────────────────────────────────\n\n  /**\n   * Resolve a workspace path to an absolute path inside the sandbox, enforcing\n   * that it stays within the workdir. Awaits the workspace root first, which\n   * for a lazy workdir may start the VM.\n   */\n  private async resolveAsync(inputPath: string): Promise<string> {\n    return this.resolveAgainst(await this.base(), inputPath);\n  }","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/agents/sandbox-filesystem.ts#L105-L141","documentation":"The sandbox filesystem's lazy `base` resolves the workspace root from workdirSource; when that source is an async function, its resolved value must be a non-empty path. An empty/falsy resolution (empty string, undefined) means the sandbox cannot anchor paths, so this error is thrown and the cached resolution promise is reset for retry.","triggerScenarios":"`base()`/`resolveAsync`/`init`/`result` invoke an async workdirSource function that resolves to '' or undefined — e.g. a sandbox whose container/workspace lookup returned nothing.","commonSituations":"Sandbox runtime failed to start or report its workspace dir, a custom workdir resolver returning '' on error instead of throwing, race where the sandbox is queried before workspace creation completed, or misconfigured sandbox templates.","solutions":["Fix the workdirSource resolver to return a valid absolute path and to throw (not return '') on failure","Check sandbox/container startup logs — the workspace may never have been created","Ensure the sandbox is fully initialized before filesystem operations (await init)","Provide a static string workdir if dynamic resolution is unnecessary","Retry after the failure — the internal resolvingBase promise is cleared, allowing a fresh resolution"],"exampleFix":"// before\nworkdirSource: async () => sandbox.workspaceDir ?? ''\n// after\nworkdirSource: async () => {\n  const dir = sandbox.workspaceDir;\n  if (!dir) throw new Error('sandbox workspace not ready');\n  return dir;\n}","handlingStrategy":"validation","validationCode":"const dir = await workdirSource();\nif (!dir || typeof dir !== 'string' || !path.isAbsolute(dir)) {\n  throw new Error('workdirSource must resolve to an absolute path');\n}","typeGuard":"const isNonEmptyPath = (v: unknown): v is string =>\n  typeof v === 'string' && v.length > 0;","tryCatchPattern":"try {\n  const base = await sandboxFs.base();\n} catch (err) {\n  if ((err as Error).message.includes('empty path')) {\n    console.error('Sandbox workspace not ready — await sandbox init and retry');\n  } else throw err;\n}","preventionTips":["Make async workdirSource throw instead of returning empty strings","Await sandbox initialization before filesystem operations","Log sandbox startup to catch failed workspace creation early"],"tags":["sandbox","filesystem","initialization"],"backgroundTag":"empty-workspace-root","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}