{"record":{"id":"5429658680ccee23","repo":"mastra-ai/mastra","slug":"woke-sandbox-but-the-mastra-server-did-not-become","errorCode":null,"errorMessage":"Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.","messagePattern":"Woke sandbox but the Mastra server did not become healthy at (.+?)(.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/client/index.ts","lineNumber":142,"sourceCode":"        `Make sure the port is declared when constructing the sandbox (e.g. \\`ports: [${port}]\\`).`,\n    );\n  }\n\n  // Some providers (e.g. Vercel) restore the filesystem but not processes on\n  // resume, while others (e.g. E2B) resume processes too — relaunch the server\n  // from the recorded launch script only when it is not answering.\n  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n  if (!healthy) {\n    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);\n    await killPreviousServer(sandbox, remoteDir);\n    await launchServer(sandbox, remoteDir);\n    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });\n  }\n  if (!healthy) {\n    const log = await resolveRemoteDir(sandbox, options.remoteDir)\n      .then(dir => tailServerLog(sandbox, dir))\n      .catch(() => '');\n    throw new Error(\n      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` +\n        (log ? `\\n\\nServer log:\\n${log}` : ''),\n    );\n  }\n\n  const info = await getInfoSafe(sandbox);\n  return handle(url, 'running', info?.timeoutAt);\n}\n\n// =============================================================================\n// Tier 3 helpers\n// =============================================================================\n\nexport interface CreateSandboxHandlerOptions {\n  /**\n   * Resolve the current sandbox URL. Called once, cached, and re-invoked when\n   * a forwarded request fails at the network level (e.g. the sandbox rotated\n   * its URL or went to sleep). Typically wraps `getDeployment`:","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/client/index.ts#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nawait getDeployment(sandbox, { healthCheckTimeoutMs: 30_000 });\n// after (slow cold start)\nawait getDeployment(sandbox, { healthCheckTimeoutMs: 120_000 });","handlingStrategy":"retry","validationCode":"// pre-check reachability before the long wait\nconst res = await fetch(`${url}/health`).catch(() => null);\nif (!res?.ok) console.warn('server not up yet; will rely on waitForHealthy retries');","typeGuard":null,"tryCatchPattern":"try {\n  await getDeployment(sandbox, { healthCheckTimeoutMs: 120_000 });\n} catch (err) {\n  if (String(err).includes('did not become healthy')) {\n    console.error('server log:', String(err).split('Server log:')[1]);\n    // inspect crash cause, fix env/config, then retry\n  } else throw err;\n}","preventionTips":["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"],"tags":["sandbox","health-check","timeout","deployment"],"backgroundTag":"health-check-timeout","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}