{"record":{"id":"f69ad4d3e18a9f34","repo":"mastra-ai/mastra","slug":"server-failed-to-start","errorCode":null,"errorMessage":"Server failed to start","messagePattern":"Server failed to start","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/dev/dev.ts","lineNumber":185,"sourceCode":"        MASTRA_TELEMETRY_COMMAND: startOptions.factory ? 'factory dev' : 'dev',\n        MASTRA_PROJECT_ROOT: resolve(dotMastraPath, '..'),\n        ...(getAnalytics()?.getDistinctId() ? { MASTRA_CLI_DISTINCT_ID: getAnalytics()!.getDistinctId() } : {}),\n        ...(startOptions?.https\n          ? {\n              MASTRA_HTTPS_KEY: startOptions.https.key.toString('base64'),\n              MASTRA_HTTPS_CERT: startOptions.https.cert.toString('base64'),\n            }\n          : {}),\n        ...(startOptions.factory ? { MASTRA_FACTORY_DEV: 'true' } : {}),\n        ...(factoryUiDist ? { MASTRACODE_UI_DIST: factoryUiDist } : {}),\n      },\n      stdio: ['inherit', 'pipe', 'pipe', 'ipc'],\n      reject: false,\n    }) as any as ChildProcess;\n\n    if (currentServerProcess?.exitCode && currentServerProcess?.exitCode !== 0) {\n      if (!currentServerProcess) {\n        throw new Error(`Server failed to start`);\n      }\n      throw new Error(\n        `Server failed to start with error: ${currentServerProcess.stderr || currentServerProcess.stdout}`,\n      );\n    }\n\n    // Filter server output to remove Studio message\n    if (currentServerProcess.stdout) {\n      currentServerProcess.stdout.on('data', (data: Buffer) => {\n        const output = data.toString();\n        if (!output.includes('Studio available') && !output.includes('👨‍💻') && !output.includes('Mastra API running')) {\n          process.stdout.write(output);\n        }\n      });\n    }\n\n    if (currentServerProcess.stderr) {\n      currentServerProcess.stderr.on('data', (data: Buffer) => {","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/dev/dev.ts#L167-L203","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Read the 'Server failed to start with error: ...' output printed alongside this failure and fix the underlying crash (syntax/import error, missing module, etc.).","Free the dev port or change --port if the server failed to bind (EADDRINUSE).","Run the suggested package update command when peer-dependency mismatches are flagged, so all @mastra/* versions align.","Re-run `mastra dev`; for restart-triggered failures, check the file you just edited first."],"exampleFix":"// terminal output before fix\nServer failed to start with error: Error: Cannot find module './generated/mastra'\n\n// after: fix the import/typo or rebuild\nimport { mastra } from './mastra'; // correct relative path, then re-run `mastra dev`","handlingStrategy":"try-catch","validationCode":"// Before starting dev, check the port is free and the entry file parses:\nimport { createServer } from 'node:net';\nconst port = 4111;\nconst s = createServer();\ns.once('error', () => console.error(`Port ${port} in use — the dev server will fail to start`));\ns.listen(port, () => { s.close(); });","typeGuard":"function isServerStartFailure(error: unknown): error is Error & { message: 'Server failed to start' | `Server failed to start with error: ${string}` } {\n  return error instanceof Error && error.message.startsWith('Server failed to start');\n}","tryCatchPattern":"try {\n  await startServer(/* ... */);\n} catch (error) {\n  if (isServerStartFailure(error)) {\n    console.error('Dev server crashed on boot. Check the printed stderr for import errors, port conflicts, or version mismatches.');\n    process.exitCode = 1;\n  } else {\n    throw error;\n  }\n}","preventionTips":["Fix the first compile/import error the watcher prints — a failed rebundle restart is the most common trigger.","Ensure the dev port is free (or pass --port) before running `mastra dev`.","Keep all @mastra/* packages on matching versions; run the CLI's suggested update command when peer mismatches appear.","Verify the Node.js version meets Mastra's requirement; native/ESM issues crash the server at boot."],"tags":["dev-server","child-process","startup-failure"],"backgroundTag":"server-failed-to-start","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}