Sandbox workspace root resolution returned an empty path

Error message

Sandbox workspace root resolution returned an empty path

What it means

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.

Source

Thrown at mastracode/sdk/src/agents/sandbox-filesystem.ts:123

      (typeof options.workdir === 'string'
        ? `sandbox-fs:${options.sandbox.id}:${options.workdir}`
        : `sandbox-fs:${options.sandbox.id}`);
  }

  /** The resolved workspace root; empty until a lazy workdir first resolves. */
  get basePath(): string {
    return this.resolvedBase ?? '';
  }

  /** Await (and memoize) the workspace root, resolving a lazy workdir once. */
  private async base(): Promise<string> {
    if (this.resolvedBase) return this.resolvedBase;
    const source = this.workdirSource;
    if (typeof source === 'string') return (this.resolvedBase = source);
    this.resolvingBase ??= Promise.resolve()
      .then(source)
      .then(resolved => {
        if (!resolved) throw new Error('Sandbox workspace root resolution returned an empty path');
        return (this.resolvedBase = resolved);
      })
      .finally(() => {
        this.resolvingBase = undefined;
      });
    return this.resolvingBase;
  }

  // ── Path handling ──────────────────────────────────────────────────────

  /**
   * Resolve a workspace path to an absolute path inside the sandbox, enforcing
   * that it stays within the workdir. Awaits the workspace root first, which
   * for a lazy workdir may start the VM.
   */
  private async resolveAsync(inputPath: string): Promise<string> {
    return this.resolveAgainst(await this.base(), inputPath);
  }

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
workdirSource: async () => sandbox.workspaceDir ?? ''
// after
workdirSource: async () => {
  const dir = sandbox.workspaceDir;
  if (!dir) throw new Error('sandbox workspace not ready');
  return dir;
}

Defensive patterns

Strategy: validation

Validate before calling

const dir = await workdirSource();
if (!dir || typeof dir !== 'string' || !path.isAbsolute(dir)) {
  throw new Error('workdirSource must resolve to an absolute path');
}

Type guard

const isNonEmptyPath = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0;

Try / catch

try {
  const base = await sandboxFs.base();
} catch (err) {
  if ((err as Error).message.includes('empty path')) {
    console.error('Sandbox workspace not ready — await sandbox init and retry');
  } else throw err;
}

Prevention

Make async workdirSource throw instead of returning empty strings
Await sandbox initialization before filesystem operations
Log sandbox startup to catch failed workspace creation early

When it happens

Trigger: `base()`/`resolveAsync`/`init`/`result` invoke an async workdirSource function that resolves to '' or undefined — e.g. a sandbox whose container/workspace lookup returned nothing.

Common situations: 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.

Related errors

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