mastra-ai/mastra · error

Worker ${startup.state} during startup${'message' in startup

Error message

Worker ${startup.state} during startup${'message' in startup && startup.message ? `: ${startup.message}` : ''}.

What it means

This error is thrown by createExecution when a sandboxed worker fails to become healthy within the startup window. waitForStartup reports one of three fatal states — 'failed' (worker process exited or reported failure), 'timed_out' (worker did not signal readiness before the deadline), or 'provider_unavailable' (the sandbox provider API could not be reached) — and the library aborts, canceling the execution on timeout before throwing.

Source

Thrown at deployers/sandbox/src/worker.ts:373

    { label: 'create worker execution namespace' },
  );
  const stdinPath = await stageInput(config, paths, input);
  const script = buildExecutionScript(config, paths, stdinPath);
  await uploadFile(config.sandbox, paths.script, Buffer.from(script));
  await runInSandbox(config.sandbox, `chmod 700 ${shellQuote(paths.script)}`);

  try {
    await launchExecution(config.sandbox, paths);
  } catch (error) {
    await writeFailedStatus(config.sandbox, paths, executionId, 'launch', error);
    throw workerPhaseError('launch', error);
  }

  const resolvePaths = async () => paths;
  const startup = await waitForStartup(config, executionId, resolvePaths);
  if (startup.state === 'timed_out') await cancelExecution(config, executionId, resolvePaths, 'startup');
  if (startup.state === 'failed' || startup.state === 'timed_out' || startup.state === 'provider_unavailable') {
    throw new Error(
      `Worker ${startup.state} during startup${'message' in startup && startup.message ? `: ${startup.message}` : ''}.`,
    );
  }

  const info = await getInfoSafe(config.sandbox);
  return deployment(config, executionId, info?.id ?? config.sandbox.id ?? 'unknown', info?.timeoutAt);
}

function execution(
  config: WorkerExecutionConfig,
  executionId: string,
  sandboxId: string,
  expiresAt?: Date,
): SandboxWorkerExecution {
  const resolvePaths = async () => executionPaths(await config.resolveRemoteDir(), executionId);
  return {
    sandboxId,
    executionId,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the appended startup.message in the error — it usually contains the worker's own failure output (stderr); fix the underlying boot failure first.
2. If state is timed_out, increase the startup timeout in the deploy config or make the worker signal readiness earlier/faster.
3. If state is provider_unavailable, verify sandbox provider credentials, network access, and provider status.
4. Reproduce by running the worker command manually inside the sandbox and inspect logs; fix entrypoint, env, and path resolution.
5. Retry the deployment after fixing; the timed-out execution is canceled automatically so a new executionId is safe.

Example fix

// before
await deployWorkerToSandbox({ sandbox, command: 'node dist/worker.js', startupTimeoutMs: 5000 });
// after
await deployWorkerToSandbox({ sandbox, command: 'node dist/worker.js --ready-file /tmp/ready', startupTimeoutMs: 30000 });

// before deploying: verify provider reachability and config sanity
if (!config.sandbox) throw new Error('sandbox provider not configured');
// optionally ping provider API/health endpoint here

function isFatalStartupState(s) { return s === 'failed' || s === 'timed_out' || s === 'provider_unavailable'; }

try {
  const deployment = await deployWorkerToSandbox(config);
} catch (e) {
  if (/Worker (failed|timed_out|provider_unavailable) during startup/.test(e.message)) {
    // inspect e.message for startup.message detail; adjust timeout/command, then retry with fresh executionId
  } else throw e;
}

When it happens

Trigger: Calling deployWorkerToSandbox (or the deployment flow) when the worker binary crashes during boot, the worker never writes its readiness/status file before the startup timeout elapses, or the sandbox provider API is unreachable/unauthorized during startup polling.

Common situations: Wrong startup command or entrypoint in the deploy config; missing env vars or files the worker needs at boot; input/output paths misresolved so the worker can't write status; slow cold-start exceeding the configured startup timeout; sandbox provider outage or expired credentials.

Related errors

• Woke sandbox but the Mastra server did not become healthy at
• Mastra server did not become healthy at ${url}${healthCheckP
• Sandbox provider "${sandbox.provider}" did not expose a publ
• No index.mjs found in "${dir}" — did the build succeed?
• Sandbox provider "${sandbox.provider}" does not support netw

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