paperclipai/paperclip · error

${payloadLabel} failed service validation and was rolled bac

Error message

${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}.

What it means

Thrown by rollbackAfterServiceValidationFailure when an updated payload failed service validation, was successfully rolled back to the prior version, and the rolled-back service restarted cleanly. The update did not stick, but the system was restored to a working state. The original validation error is attached as `cause` so the operator can diagnose why the new payload failed.

Source

Thrown at cli/src/commands/update.ts:164

}
function emit(options: UpdateOptions, value: Record<string, unknown>, message: string): void { if (options.json) console.log(JSON.stringify(value, null, 2)); else console.log(message); }

async function rollbackAfterServiceValidationFailure(
  paths: InstallStorePaths,
  restartActiveService: (expectedVersion: string) => Promise<boolean>,
  validationError: unknown,
  payloadLabel: string,
): Promise<never> {
  const rolledBack = await withInstallStoreLock(async () => rollbackManagedInstall(paths), paths);
  try {
    await restartActiveService(rolledBack.version);
  } catch (restartError) {
    throw new Error(
      `${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}, but the rolled-back service also failed to restart.`,
      { cause: new AggregateError([validationError, restartError]) },
    );
  }
  throw new Error(`${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}.`, { cause: validationError });
}

export async function updateCommand(options: UpdateOptions, overrides: Partial<Dependencies> = {}): Promise<void> {
  const paths = overrides.paths ?? resolveInstallStorePaths();
  const executablePath = overrides.executablePath ?? process.argv[1] ?? "";
  const runCommand = overrides.runCommand ?? execFileAsync;
  const mode = detectInstallMode(executablePath, paths);
  const manifest = readInstallManifest(paths);
  if (options.rollback) {
    if (mode !== "managed") throw new Error("--rollback is only available for managed installs.");
    if (options.dryRun) { emit(options, { mode, action: "rollback", dryRun: true, target: manifest?.previous[0]?.version ?? null }, `Would roll back to ${manifest?.previous[0]?.version ?? "the previous payload"}.`); return; }
    const next = await withInstallStoreLock(async () => rollbackManagedInstall(paths), paths);
    const restarted = await (overrides.restartActiveService ?? restartActiveManagedService)(next.version);
    emit(options, { mode, action: "rollback", version: next.version, restarted }, pc.green(`Rolled back to paperclipai ${next.version}${restarted ? " and restarted the active service" : ""}. Database migrations are not reversed; restore the pre-update backup if needed.`));
    return;
  }
  if (mode === "npx") { emit(options, { mode, action: "install" }, "This is an ephemeral npx install. Run `paperclipai install`, then use `paperclipai update` from the managed shim."); return; }
  if (mode === "source" || mode === "unknown") { emit(options, { mode, action: "manual" }, "This appears to be a source checkout. Update it with `git pull` followed by `pnpm install`; Paperclip will not mutate the repository."); return; }

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Read the `cause` error to identify why the new payload failed to start, then fix or report it.
2. Confirm the rolled-back service is healthy: `paperclipai service status`.
3. Pin to the working version with `paperclipai update --version <rolled-back-version>` until the new release is fixed.
4. If the cause is a half-applied DB migration, restore the pre-update backup before retrying the update.

try {
  await updateCommand(options);
} catch (error) {
  if (error instanceof Error && error.message.includes('failed service validation and was rolled back')) {
    // system is back on the old version — inspect error.cause to diagnose the new payload
    console.error('New payload failed:', error.cause);
    // optionally pin to the rolled-back version explicitly
  } else throw error;
}

When it happens

Trigger: Reached from updateCommand's catch blocks (lines 203-211 for git, 257-265 for npm) when the new payload installs but restartActiveManagedService throws. The rollback path then rolls back and restarts the old service without error, landing on this terminal throw.

Common situations: New release has a startup bug (bad migration, missing env, port-binding error). Build-script-produced git payload is broken. Incompatible Node/runtime version for the new payload only.

Related errors

• No managed install was found to roll back.
• No previous managed payload is available for rollback.
• ${payloadLabel} failed service validation and was rolled bac
• --rollback is only available for managed installs.
• The Paperclip database is not running or reachable, so the p

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