paperclipai/paperclip · error

Failed to prepare workspace build artifacts before starting

Error message

Failed to prepare workspace build artifacts before starting the Paperclip dev server.\n${formatError(result.error)}

What it means

Thrown by ensureDevWorkspaceBuildDeps() when spawnSync itself fails to launch the `scripts/ensure-plugin-build-deps.mjs` script (result.error set). This is a spawn-level failure (ENOENT, EACCES, timeout-abort), distinct from the script exiting non-zero. It runs only in dev workspace mode where `server/src/index.ts` exists.

Source

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

  if (process.env.PAPERCLIP_UI_DEV_MIDDLEWARE !== undefined) return;
  const normalized = entrypoint.replaceAll("\\", "/");
  if (normalized.endsWith("/server/src/index.ts") || normalized.endsWith("@paperclipai/server/src/index.ts")) {
    process.env.PAPERCLIP_UI_DEV_MIDDLEWARE = "true";
  }
}

function ensureDevWorkspaceBuildDeps(projectRoot: string): void {
  const buildScript = path.resolve(projectRoot, "scripts/ensure-plugin-build-deps.mjs");
  if (!fs.existsSync(buildScript)) return;

  const result = spawnSync(process.execPath, [buildScript], {
    cwd: projectRoot,
    stdio: "inherit",
    timeout: 120_000,
  });

  if (result.error) {
    throw new Error(
      `Failed to prepare workspace build artifacts before starting the Paperclip dev server.\n${formatError(result.error)}`,
    );
  }

  if ((result.status ?? 1) !== 0) {
    throw new Error(
      "Failed to prepare workspace build artifacts before starting the Paperclip dev server.",
    );
  }
}

async function importServerEntry(): Promise<StartedServer> {
  // Dev mode: try local workspace path (monorepo with tsx)
  const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
  const devEntry = path.resolve(projectRoot, "server/src/index.ts");
  if (fs.existsSync(devEntry)) {
    ensureDevWorkspaceBuildDeps(projectRoot);
    maybeEnableUiDevMiddleware(devEntry);

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Read the formatted error in the message — ENOENT points to node or the script; EACCES to permissions.
2. Run the script manually to see the real failure: `node scripts/ensure-plugin-build-deps.mjs`.
3. If it is a timeout, profile the plugin build deps script and speed it up or raise resources.
4. Reinstall workspace deps: `pnpm install`.

Example fix

# before: dev boot fails with spawn error
paperclipai run
# after: run the script directly to surface the cause
node scripts/ensure-plugin-build-deps.mjs

import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
function precheckBuildScript(projectRoot: string): void {
  const script = `${projectRoot}/scripts/ensure-plugin-build-deps.mjs`;
  if (!fs.existsSync(script)) return;
  if (!fs.existsSync(process.execPath)) throw new Error(`Node not found at ${process.execPath}`);
}

try {
  ensureDevWorkspaceBuildDeps(projectRoot);
} catch (err) {
  console.error('Build-deps prep failed; run manually:', err);
  throw err;
}

When it happens

Trigger: Running `paperclipai run` (or dev server boot) inside the monorepo when spawnSync fails to exec `process.execPath scripts/ensure-plugin-build-deps.mjs`. Producers: node binary not resolvable via process.execPath, script missing or not executable, EACCES, or the spawn hit the 120s timeout and was aborted (result.error set on timeout-kill in some Node versions).

Common situations: Broken Node install, file permission errors on the script, an interrupted dev boot that left a half-built state, or a slow plugin build exceeding the 120s timeout.

Related errors

• Failed to prepare workspace build artifacts before starting
• API error ${response.status}: ${bytes.toString("utf8")}
• workspaceId is required for update
• Circular workspace dependency while staging ${packageName}.
• Git install cannot stage workspace dependency ${packageName}

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