paperclipai/paperclip · critical

Paperclip server failed to start.\n${formatError(err)}

Error message

Paperclip server failed to start.\n${formatError(err)}

What it means

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.

Source

Thrown at cli/src/commands/run.ts:210

    const mod = await import(pathToFileURL(devEntry).href);
    return await startServerFromModule(mod, devEntry);
  }

  // Production mode: import the published @paperclipai/server package
  try {
    const mod = await import("@paperclipai/server");
    return await startServerFromModule(mod, "@paperclipai/server");
  } catch (err) {
    const missingSpecifier = getMissingModuleSpecifier(err);
    const missingServerEntrypoint = !missingSpecifier || missingSpecifier === "@paperclipai/server";
    if (isModuleNotFoundError(err) && missingServerEntrypoint) {
      throw new Error(
        `Could not locate a Paperclip server entrypoint.\n` +
          `Tried: ${devEntry}, @paperclipai/server\n` +
          `${formatError(err)}`,
      );
    }
    throw new Error(
      `Paperclip server failed to start.\n` +
        `${formatError(err)}`,
    );
  }
}

function shouldGenerateBootstrapInviteAfterStart(config: PaperclipConfig): boolean {
  return config.server.deploymentMode === "authenticated" && config.database.mode === "embedded-postgres";
}

async function startServerFromModule(mod: unknown, label: string): Promise<StartedServer> {
  const startServer = (mod as { startServer?: () => Promise<StartedServer> }).startServer;
  if (typeof startServer !== "function") {
    throw new Error(`Paperclip server entrypoint did not export startServer(): ${label}`);
  }
  return await startServer();
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Read the formatted error in the message — it names the real cause (port, env, native module).
2. Free the port or change the configured port; set/fix DATABASE_URL and required env vars.
3. Reinstall dependencies to fix missing transitive modules: `pnpm install`.
4. On Node version changes, rebuild native modules: `pnpm rebuild`.

Example fix

# before: server fails to start (port in use)
paperclipai run
# after: free the port and set DB url
PORT=3200 DATABASE_URL=postgres://... paperclipai run

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function assertServerStartable(): void {
  require.resolve('@paperclipai/server');
  if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL must be set to start the server.');
}

try {
  await import('@paperclipai/server');
} catch (err) {
  console.error('Server start failed:', err);
  // surface port/env/native errors distinctly
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not locate a Paperclip server entrypoint.\nTried: ${de
• Paperclip server entrypoint did not export startServer(): ${
• Failed to parse JSON at ${filePath}: ${err instanceof Error
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• Company ID is required. Pass --company-id, set PAPERCLIP_COM

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/916f55e0c9f3767f. Report an issue: GitHub.