mastra-ai/mastra · error · Error

Server failed to start

Error message

Server failed to start

What it means

In `mastra dev`, the CLI spawns the Mastra server as a child process via execa. After spawn, startServer checks the child's exitCode; if it already exited non-zero, it throws 'Server failed to start' (the bare variant fires only when currentServerProcess is falsy — a defensive branch that is effectively unreachable because the outer `if` already required currentServerProcess to be truthy). Practically, users see the sibling message 'Server failed to start with error: ...' containing the child's stderr/stdout when the dev server crashes immediately.

Source

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

        MASTRA_TELEMETRY_COMMAND: startOptions.factory ? 'factory dev' : 'dev',
        MASTRA_PROJECT_ROOT: resolve(dotMastraPath, '..'),
        ...(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) => {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the 'Server failed to start with error: ...' output printed alongside this failure and fix the underlying crash (syntax/import error, missing module, etc.).
2. Free the dev port or change --port if the server failed to bind (EADDRINUSE).
3. Run the suggested package update command when peer-dependency mismatches are flagged, so all @mastra/* versions align.
4. Re-run `mastra dev`; for restart-triggered failures, check the file you just edited first.

Example fix

// terminal output before fix
Server failed to start with error: Error: Cannot find module './generated/mastra'

// after: fix the import/typo or rebuild
import { mastra } from './mastra'; // correct relative path, then re-run `mastra dev`

// Before starting dev, check the port is free and the entry file parses:
import { createServer } from 'node:net';
const port = 4111;
const s = createServer();
s.once('error', () => console.error(`Port ${port} in use — the dev server will fail to start`));
s.listen(port, () => { s.close(); });

function isServerStartFailure(error: unknown): error is Error & { message: 'Server failed to start' | `Server failed to start with error: ${string}` } {
  return error instanceof Error && error.message.startsWith('Server failed to start');
}

try {
  await startServer(/* ... */);
} catch (error) {
  if (isServerStartFailure(error)) {
    console.error('Dev server crashed on boot. Check the printed stderr for import errors, port conflicts, or version mismatches.');
    process.exitCode = 1;
  } else {
    throw error;
  }
}

When it happens

Trigger: `mastra dev` (or rebundleAndRestart after a code change) where the spawned server process exits non-zero before or immediately after the exitCode check: syntax/import errors in the built bundle, port binding failures, missing native modules, or a crash on boot.

Common situations: A recent code edit introduced an import/syntax error so the rebundled server dies on restart; another process already holds the dev port; mismatched @mastra/* peer versions crash the server on startup (the CLI then hints at an update command); Node version incompatibilities.

Related errors

• Server failed to start with error: ${currentServerProcess.st
• Refusing to pass unsafe argument to shell command: ${JSON.st

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