mastra-ai/mastra · error · Error

Server failed to start with error: ${currentServerProcess.st

Error message

Server failed to start with error: ${currentServerProcess.stderr || currentServerProcess.stdout}

What it means

This error is thrown by the `mastra dev` CLI command when the spawned Hono dev server child process exits with a non-zero code before or during startup. The CLI surfaces the child process's stderr (falling back to stdout) in the message so the underlying server crash reason is visible. It is a wrapper error: the real cause is whatever the embedded server printed.

Source

Thrown at packages/cli/src/commands/dev/dev.ts:187

        ...(getAnalytics()?.getDistinctId() ? { MASTRA_CLI_DISTINCT_ID: getAnalytics()!.getDistinctId() } : {}),
        ...(startOptions?.https
          ? {
              MASTRA_HTTPS_KEY: startOptions.https.key.toString('base64'),
              MASTRA_HTTPS_CERT: startOptions.https.cert.toString('base64'),
            }
          : {}),
        ...(startOptions.factory ? { MASTRA_FACTORY_DEV: 'true' } : {}),
        ...(factoryUiDist ? { MASTRACODE_UI_DIST: factoryUiDist } : {}),
      },
      stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
      reject: false,
    }) as any as ChildProcess;

    if (currentServerProcess?.exitCode && currentServerProcess?.exitCode !== 0) {
      if (!currentServerProcess) {
        throw new Error(`Server failed to start`);
      }
      throw new Error(
        `Server failed to start with error: ${currentServerProcess.stderr || currentServerProcess.stdout}`,
      );
    }

    // Filter server output to remove Studio message
    if (currentServerProcess.stdout) {
      currentServerProcess.stdout.on('data', (data: Buffer) => {
        const output = data.toString();
        if (!output.includes('Studio available') && !output.includes('👨‍💻') && !output.includes('Mastra API running')) {
          process.stdout.write(output);
        }
      });
    }

    if (currentServerProcess.stderr) {
      currentServerProcess.stderr.on('data', (data: Buffer) => {
        const output = data.toString();
        if (!output.includes('Studio available') && !output.includes('👨‍💻') && !output.includes('Mastra API running')) {

View on GitHub (pinned to 75dd419e61)

Solutions

Read the stderr text appended after 'Server failed to start with error:' — it contains the actual server-side exception and fix that first
Check that nothing else occupies the dev port and adjust PORT if needed
Run `mastra dev --debug` or build (`mastra build`) to surface bundler/import errors
Verify all mastra agents/tools/workflows construct successfully without network/DB dependencies failing at import time
Update @mastra/* packages to aligned versions — mismatched core/cli versions can crash the server at boot

Example fix

// before: server crashes on startup because env var is missing
const store = new PostgresStore({ connectionString: process.env.DATABASE_URL! });
// after: fail fast with a clear message before the server boots
const connectionString = process.env.DATABASE_URL;
if (!connectionString) throw new Error('DATABASE_URL is required to run mastra dev');
const store = new PostgresStore({ connectionString });

Defensive patterns

Strategy: try-catch

Validate before calling

import { spawnSync } from 'node:child_process';
const port = Number(process.env.PORT ?? 4111);
const probe = spawnSync('node', ['-e', `require('net').createConnection(${port}).on('connect',()=>{console.error('in-use');process.exit(1)}).on('error',()=>process.exit(0))`]);
if (probe.status === 1) throw new Error(`Port ${port} already in use; free it or set PORT before running mastra dev`);
if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL must be set before mastra dev');

Type guard

function hasStartupError(p: { exitCode: number | null } | null): p is { exitCode: number } & { stderr: string | null; stdout: string | null } {
  return p !== null && typeof p.exitCode === 'number' && p.exitCode !== 0;
}

Try / catch

try {
  await dev({ port });
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  const serverOutput = msg.replace('Server failed to start with error: ', '');
  console.error('Dev server failed to boot. Server output:\n' + serverOutput);
  process.exitCode = 1;
}

Prevention

Always read the stderr tail included in the error message before changing code
Keep mastra core/cli/deps versions aligned and run updates together
Ensure all module-level side effects (DB, storage, API clients) tolerate missing env or defer lazily
Check port availability / set PORT before launching in shared dev environments
Run `mastra build` in CI to catch bundling/import errors that crash the dev server

When it happens

Trigger: Running `mastra dev` where the server child process sets exitCode !== 0; typically the bundled server fails at import time (bad mastra instance, TS compile/bundler error, port binding failure, broken tool/agent imports) and dies immediately.

Common situations: A syntax or import error in src/mastra files that bundling didn't catch; another process already listening on the port; an invalid DATABASE_URL or storage config throwing at module init; incompatible env vars expected by the server; a plugin/custom registerApiRoute throwing during bootstrap.

Related errors

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