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.

What it means

Thrown by ensureDevWorkspaceBuildDeps() when the plugin build-deps script launched successfully but exited with a non-zero status. Unlike error 169, the spawn succeeded; the script itself failed (compile error, missing dep, plugin build failure).

Source

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

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);
    const mod = await import(pathToFileURL(devEntry).href);
    return await startServerFromModule(mod, devEntry);
  }

  // Production mode: import the published @paperclipai/server package
  try {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Scroll up: the script's stderr/stdout is printed before the error — fix the reported build failure.
2. Reinstall plugins/workspace deps: `pnpm install`.
3. Clean and rebuild plugin packages per the repo's build instructions.
4. Run `node scripts/ensure-plugin-build-deps.mjs` directly to iterate.

Example fix

# before: dev boot fails with non-zero build exit
paperclipai run
# after: reproduce and fix the plugin build
node scripts/ensure-plugin-build-deps.mjs
pnpm -r build

import { spawnSync } from 'node:child_process';
function runBuildDeps(projectRoot: string): void {
  const r = spawnSync(process.execPath, ['scripts/ensure-plugin-build-deps.mjs'], {cwd: projectRoot, stdio: 'inherit'});
  if (r.error || (r.status ?? 1) !== 0) throw new Error('Build deps failed; see output above.');
}

const status = spawnSync(process.execPath, [script], {stdio: 'inherit'}).status ?? 1;
if (status !== 0) {
  console.error('Plugin build deps exited', status);
  process.exit(status);
}

When it happens

Trigger: Running dev server boot inside the monorepo; `scripts/ensure-plugin-build-deps.mjs` runs via spawnSync with stdio inherit and returns `result.status` other than 0 (or null, which the `?? 1` coerces to failure).

Common situations: A plugin package fails to build because its dependencies are not installed, a TypeScript error in a plugin, or a stale dist after a branch switch. The script's own output (inherited to the terminal) shows the real cause before this throw.

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/b5e859e02a514ad1. Report an issue: GitHub.