Sandbox '${this.id}' onStart hook failed: ${error instanceof

Error message

Sandbox '${this.id}' onStart hook failed: ${error instanceof Error ? error.message : error}

What it means

Thrown by _executeStart in MastraSandbox when a user-supplied `onStart` hook throws during sandbox startup. The sandbox status is set to 'error' and the original error is attached as `cause`. This guards startup: a broken hook must not leave a sandbox that claims to be running while its initialization logic failed.

Source

Thrown at packages/core/src/workspace/sandbox/mastra-sandbox.ts:458

      // start() always observe a sandbox whose hook finished.
      this.status = 'running';
    } catch (error) {
      this.status = 'error';
      throw error;
    }

    const outcome = result?.outcome;

    // Hook failures are FATAL: a caller must never observe a running sandbox
    // whose setup failed. Nothing latches, so the next start() retries it.
    // The environment acquired above is NOT released first: providers that
    // implement find() reconnect to it on retry, but a create-only provider
    // provisions another one and leaves the first to its idle timeout.
    try {
      await this._onStart?.({ sandbox: this, outcome });
    } catch (error) {
      this.status = 'error';
      throw new Error(`Sandbox '${this.id}' onStart hook failed: ${error instanceof Error ? error.message : error}`, {
        cause: error,
      });
    }

    // Process any pending mounts after successful start
    // Mount failures are tracked individually in MountManager and
    // shouldn't mark the sandbox itself as errored
    try {
      await this.mounts?.processPending();
    } catch (error) {
      // Mount failures are tracked in MountManager — log but don't affect sandbox status
      this.logger.warn('Unexpected error processing pending mounts', { error });
    }

    return result;
  }

  // ---------------------------------------------------------------------------

View on GitHub (pinned to 75dd419e61)

Solutions

Inspect error.cause to see the real error thrown by your onStart hook and fix the hook's logic.
Make the hook idempotent and wrap its fallible external calls with retry logic so transient failures don't fail startup.
If the hook's work is optional, catch its internal errors inside the hook and log instead of throwing.
Verify any env vars/secrets the hook needs exist in the runtime environment before calling start().

Example fix

// before
new MastraSandbox({ onStart: async ({ sandbox }) => { await uploadAssets(sandbox.id); } });
// after
new MastraSandbox({
  onStart: async ({ sandbox }) => {
    for (let i = 0; i < 3; i++) {
      try { await uploadAssets(sandbox.id); return; }
      catch (e) { if (i === 2) logger.warn('upload failed, continuing', e); }
    }
  },
});

Defensive patterns

Strategy: try-catch

Validate before calling

const hook = opts.onStart;
if (typeof hook !== 'function') throw new TypeError('onStart must be a function');
// pre-check external deps the hook uses
if (!process.env.UPLOAD_URL) throw new Error('UPLOAD_URL required by onStart hook');

Type guard

function isHookError(e: unknown): e is Error & { cause: unknown } {
  return e instanceof Error && /onStart hook failed/.test(e.message) && 'cause' in e;
}

Try / catch

try {
  await sandbox.start();
} catch (e) {
  if (e instanceof Error && /onStart hook failed/.test(e.message)) {
    logger.error('onStart hook failed', { cause: e.cause });
    // fix hook or retry with backoff
  } else throw e;
}

Prevention

Keep onStart hooks minimal and idempotent; move heavy provisioning elsewhere.
Add internal try/catch with retries around fallible external calls in the hook.
Validate env vars and config the hook depends on before calling start().

When it happens

Trigger: Calling sandbox.start() (directly or via ensureRunning) when the sandbox has an `onStart` option/callback that throws — e.g. invalid data in the hook, a failed network call inside the hook, or a typo like calling an undefined variable inside the hook body.

Common situations: Provisioning steps (uploading files, registering DNS, warm-up API calls) placed in onStart that fail transiently; referencing `this` incorrectly in an arrow/loose function; fetching env vars that are missing in the deployment environment.

Related errors

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