{"record":{"id":"435735e6e7d22cc2","repo":"DayuanJiang/next-ai-draw-io","slug":"server-startup-timeout-after-timeout-ms","errorCode":null,"errorMessage":"Server startup timeout after ${timeout}ms","messagePattern":"Server startup timeout after (.+?)ms","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"electron/main/next-server.ts","lineNumber":41,"sourceCode":"}\n\n/**\n * Wait for the server to be ready by polling the health endpoint\n */\nasync function waitForServer(url: string, timeout = 30000): Promise<void> {\n    const start = Date.now()\n    while (Date.now() - start < timeout) {\n        try {\n            const response = await fetch(url)\n            if (response.ok || response.status < 500) {\n                return\n            }\n        } catch {\n            // Server not ready yet\n        }\n        await new Promise((resolve) => setTimeout(resolve, 100))\n    }\n    throw new Error(`Server startup timeout after ${timeout}ms`)\n}\n\n/**\n * Start the Next.js standalone server using Electron's utilityProcess\n * This API is designed for running Node.js code in the background\n */\nexport async function startNextServer(): Promise<string> {\n    const resourcePath = getResourcePath()\n    const serverPath = path.join(resourcePath, \"server.js\")\n\n    console.log(`Starting Next.js server from: ${resourcePath}`)\n    console.log(`Server script path: ${serverPath}`)\n\n    // Verify server script exists before attempting to start\n    if (!existsSync(serverPath)) {\n        throw new Error(\n            `Server script not found at ${serverPath}. ` +\n                \"Please ensure the app was built correctly with 'npm run build'.\",","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/DayuanJiang/next-ai-draw-io/blob/155ef4f7acd29c9d46fb6fc35c92e6e6955a6ce1/electron/main/next-server.ts#L23-L59","documentation":"waitForServer polls the Next.js server health endpoint every 100ms and throws when it does not become ready within the configured timeout (default ms in startNextServer).","triggerScenarios":"Electron starts the Next.js standalone server as a utilityProcess and the server crashes on boot, takes too long to compile/bind the port, or the health endpoint path/port is wrong.","commonSituations":"Missing build output (running packaged app without npm run build), port already in use, crash inside next server startup, slow disk/AV scanning delaying startup, or timeout set too low.","solutions":["Check the utilityProcess/server logs for the real startup crash","Run npm run build before packaging/starting; verify serverPath exists","Increase the timeout passed to waitForServer for slow machines","Ensure the expected port is free (lsof -i) and the health check URL matches the bound port"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const started = await isPortResponsive(port) // quick TCP/health probe before assuming readiness","typeGuard":null,"tryCatchPattern":"try {\n  await waitForServer(port, timeout)\n} catch (e) {\n  if ((e as Error).message.includes('timeout')) {\n    showStartupDiagnostics(); captureUtilityProcessLogs()\n  }\n}","preventionTips":["Run npm run build before launching/packaging","Increase timeout on slower hardware","Log utilityProcess stderr to catch the underlying crash early","Free the expected port before start"],"tags":["electron","nextjs","startup","timeout","server"],"backgroundTag":"server-startup-timeout","analyzedSha":"155ef4f7acd29c9d46fb6fc35c92e6e6955a6ce1","analyzedAt":"2026-08-27T11:40:38.297Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}