{"record":{"id":"7d37cab5c6a3778d","repo":"mastra-ai/mastra","slug":"mastra-server-did-not-become-healthy-at-url-he","errorCode":null,"errorMessage":"Mastra server did not become healthy at ${url}${healthCheckPath} within ${healthCheckTimeoutMs}ms.","messagePattern":"Mastra server did not become healthy at (.+?)(.+?) within (.+?)ms\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/engine.ts","lineNumber":152,"sourceCode":"\n  // 4. Write the launch script and start the new server (the previous one was\n  // stopped before extraction).\n  const launchScript = buildLaunchScript({ remoteDir, port, env: mergedEnv });\n  await uploadFile(sandbox, `${remoteDir}/${SERVER_SCRIPT}`, Buffer.from(launchScript));\n  await runInSandbox(sandbox, `chmod 700 ${shellQuote(`${remoteDir}/${SERVER_SCRIPT}`)}`);\n\n  logger.info('Starting Mastra server...');\n  await launchServer(sandbox, remoteDir);\n\n  // 5. Wait for the server to answer on its public URL.\n  const healthy = await waitForHealthy(url, {\n    path: healthCheckPath,\n    timeoutMs: healthCheckTimeoutMs,\n    intervalMs: healthCheckIntervalMs,\n  });\n  if (!healthy) {\n    const log = await tailServerLog(sandbox, remoteDir).catch(() => '');\n    throw new Error(\n      `Mastra server did not become healthy at ${url}${healthCheckPath} within ${healthCheckTimeoutMs}ms.` +\n        (log ? `\\n\\nServer log:\\n${log}` : '\\n\\n(no server log output captured)'),\n    );\n  }\n\n  const info = await getInfoSafe(sandbox);\n\n  return {\n    url,\n    sandboxId: info?.id ?? sandbox.id,\n    expiresAt: info?.timeoutAt,\n    stop: async () => {\n      await sandbox.stop?.();\n    },\n    destroy: async () => {\n      await sandbox.destroy?.();\n    },\n    logs: (lines?: number) => tailServerLog(sandbox, remoteDir, lines),","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/engine.ts#L134-L170","documentation":"During deployToSandbox, after installing and starting the Mastra server inside the sandbox, the engine polls the health endpoint until timeout. If waitForHealthy never succeeds within healthCheckTimeoutMs, this error is thrown, including the server log tail (or a note that no log was captured) for diagnosis.","triggerScenarios":"deployToSandbox starts the server and waitForHealthy({ path: healthCheckPath, timeoutMs, intervalMs }) exhausts its timeout while the server is down, misconfigured, or still booting.","commonSituations":"Install step failed silently (broken dependencies), server crashes on missing env/secrets, healthCheckPath mismatch, port/host misconfiguration, slow startup exceeding the timeout, provider network restrictions blocking health check traffic.","solutions":["Read the 'Server log:' section in the error for the root cause","Increase healthCheckTimeoutMs (and/or intervalMs) for slower environments","Verify healthCheckPath and PORT match the server's actual configuration","Ensure required env vars are exported in the launch script/env passed to the deploy","Check the install step succeeded (npm install --omit=dev output)"],"exampleFix":"// before\nawait deployToSandbox(sandbox, { healthCheckTimeoutMs: 30_000 });\n// after\nawait deployToSandbox(sandbox, {\n  healthCheckTimeoutMs: 180_000,\n  env: { DATABASE_URL: process.env.DATABASE_URL },\n});","handlingStrategy":"retry","validationCode":"// preflight: ensure install/start inputs are sane before the timed health wait\nif (!existsSync(join(dir, 'index.mjs'))) throw new Error('build first');\nif (!env.PORT) throw new Error('PORT must be provided in env');","typeGuard":null,"tryCatchPattern":"try {\n  await deployToSandbox(sandbox, { healthCheckTimeoutMs: 180_000 });\n} catch (err) {\n  if (String(err).includes('did not become healthy')) {\n    const log = String(err).split('Server log:')[1] ?? '(no log)';\n    console.error('boot failure:', log);\n  } else throw err;\n}","preventionTips":["Ship every required env var into the deploy env option","Use generous healthCheckTimeoutMs in CI/cold environments","Verify healthCheckPath matches the server's health endpoint","Fix install/build errors surfaced before the health wait"],"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"}