{"record":{"id":"916f55e0c9f3767f","repo":"paperclipai/paperclip","slug":"paperclip-server-failed-to-start-n-formaterror-e","errorCode":null,"errorMessage":"Paperclip server failed to start.\\n${formatError(err)}","messagePattern":"Paperclip server failed to start\\.\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cli/src/commands/run.ts","lineNumber":210,"sourceCode":"    const mod = await import(pathToFileURL(devEntry).href);\n    return await startServerFromModule(mod, devEntry);\n  }\n\n  // Production mode: import the published @paperclipai/server package\n  try {\n    const mod = await import(\"@paperclipai/server\");\n    return await startServerFromModule(mod, \"@paperclipai/server\");\n  } catch (err) {\n    const missingSpecifier = getMissingModuleSpecifier(err);\n    const missingServerEntrypoint = !missingSpecifier || missingSpecifier === \"@paperclipai/server\";\n    if (isModuleNotFoundError(err) && missingServerEntrypoint) {\n      throw new Error(\n        `Could not locate a Paperclip server entrypoint.\\n` +\n          `Tried: ${devEntry}, @paperclipai/server\\n` +\n          `${formatError(err)}`,\n      );\n    }\n    throw new Error(\n      `Paperclip server failed to start.\\n` +\n        `${formatError(err)}`,\n    );\n  }\n}\n\nfunction shouldGenerateBootstrapInviteAfterStart(config: PaperclipConfig): boolean {\n  return config.server.deploymentMode === \"authenticated\" && config.database.mode === \"embedded-postgres\";\n}\n\nasync function startServerFromModule(mod: unknown, label: string): Promise<StartedServer> {\n  const startServer = (mod as { startServer?: () => Promise<StartedServer> }).startServer;\n  if (typeof startServer !== \"function\") {\n    throw new Error(`Paperclip server entrypoint did not export startServer(): ${label}`);\n  }\n  return await startServer();\n}\n","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/run.ts#L192-L228","documentation":"Thrown by importServerEntry() when the `@paperclipai/server` import was found but failed for a non-MODULE_NOT_FOUND reason, or a transitive module error inside the server. The server package resolved but its import or startServer threw.","triggerScenarios":"Production boot where @paperclipai/server is installed but importing it throws — port already in use, missing/bad DATABASE_URL, config validation failure, native module crash, or a transitive dependency missing (specifier other than the server package). The original error is formatted into the message.","commonSituations":"Server config errors (bad DATABASE_URL, missing env), port 3100 already bound, an incompatible Node ABI crashing a native dep, or a partial install where a transitive server dependency is missing.","solutions":["Read the formatted error in the message — it names the real cause (port, env, native module).","Free the port or change the configured port; set/fix DATABASE_URL and required env vars.","Reinstall dependencies to fix missing transitive modules: `pnpm install`.","On Node version changes, rebuild native modules: `pnpm rebuild`."],"exampleFix":"# before: server fails to start (port in use)\npaperclipai run\n# after: free the port and set DB url\nPORT=3200 DATABASE_URL=postgres://... paperclipai run","handlingStrategy":"try-catch","validationCode":"import { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);\nfunction assertServerStartable(): void {\n  require.resolve('@paperclipai/server');\n  if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL must be set to start the server.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await import('@paperclipai/server');\n} catch (err) {\n  console.error('Server start failed:', err);\n  // surface port/env/native errors distinctly\n  throw err;\n}","preventionTips":["Validate required server env (DATABASE_URL, PORT availability) before launching.","Free or change the server port if 3100 is in use."],"tags":["server","startup","runtime-error","run","config"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}