Woke sandbox but the Mastra server did not become healthy at

Error message

Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.

What it means

Thrown by getDeployment after successfully waking/starting the sandboxed Mastra server but the HTTP health check (default path /health) never reported healthy within the timeout. The library tails the remote server log and appends it to help diagnose the startup failure.

Source

Thrown at deployers/sandbox/src/client/index.ts:142

        `Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`,
    );
  }

  // Some providers (e.g. Vercel) restore the filesystem but not processes on
  // resume, while others (e.g. E2B) resume processes too — relaunch the server
  // from the recorded launch script only when it is not answering.
  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });
  if (!healthy) {
    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
    await killPreviousServer(sandbox, remoteDir);
    await launchServer(sandbox, remoteDir);
    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });
  }
  if (!healthy) {
    const log = await resolveRemoteDir(sandbox, options.remoteDir)
      .then(dir => tailServerLog(sandbox, dir))
      .catch(() => '');
    throw new Error(
      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` +
        (log ? `\n\nServer log:\n${log}` : ''),
    );
  }

  const info = await getInfoSafe(sandbox);
  return handle(url, 'running', info?.timeoutAt);
}

// =============================================================================
// Tier 3 helpers
// =============================================================================

export interface CreateSandboxHandlerOptions {
  /**
   * Resolve the current sandbox URL. Called once, cached, and re-invoked when
   * a forwarded request fails at the network level (e.g. the sandbox rotated
   * its URL or went to sleep). Typically wraps `getDeployment`:

View on GitHub (pinned to 75dd419e61)

Solutions

Inspect the 'Server log:' section of the error for the actual crash cause
Increase healthCheckTimeoutMs for slow cold starts
Verify healthCheckPath matches the server's health endpoint
Confirm required env vars/secrets are provided to the sandbox
Verify the server binds to 0.0.0.0 on the declared port

Example fix

// before
await getDeployment(sandbox, { healthCheckTimeoutMs: 30_000 });
// after (slow cold start)
await getDeployment(sandbox, { healthCheckTimeoutMs: 120_000 });

Defensive patterns

Strategy: retry

Validate before calling

// pre-check reachability before the long wait
const res = await fetch(`${url}/health`).catch(() => null);
if (!res?.ok) console.warn('server not up yet; will rely on waitForHealthy retries');

Try / catch

try {
  await getDeployment(sandbox, { healthCheckTimeoutMs: 120_000 });
} catch (err) {
  if (String(err).includes('did not become healthy')) {
    console.error('server log:', String(err).split('Server log:')[1]);
    // inspect crash cause, fix env/config, then retry
  } else throw err;
}

Prevention

Set healthCheckTimeoutMs generously for cold starts
Match healthCheckPath to your server's real health route
Ship all required env vars/secrets into the sandbox
Confirm the server binds 0.0.0.0, not 127.0.0.1

When it happens

Trigger: getDeployment starts the server and calls waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1000 }); if every poll fails until the timeout expires, this error is thrown.

Common situations: Missing env vars (e.g. missing DB URL) crashing the server on boot; install/build failures leaving a broken bundle; wrong healthCheckPath (server exposes a different health route); server binding to the wrong host/port; cold-start exceeding healthCheckTimeoutMs.

Related errors

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