{"record":{"id":"bed1e62e61b66ccd","repo":"paperclipai/paperclip","slug":"payloadlabel-failed-service-validation-and-was-bed1e6","errorCode":null,"errorMessage":"${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}.","messagePattern":"(.+?) failed service validation and was rolled back to (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/update.ts","lineNumber":164,"sourceCode":"}\nfunction emit(options: UpdateOptions, value: Record<string, unknown>, message: string): void { if (options.json) console.log(JSON.stringify(value, null, 2)); else console.log(message); }\n\nasync function rollbackAfterServiceValidationFailure(\n  paths: InstallStorePaths,\n  restartActiveService: (expectedVersion: string) => Promise<boolean>,\n  validationError: unknown,\n  payloadLabel: string,\n): Promise<never> {\n  const rolledBack = await withInstallStoreLock(async () => rollbackManagedInstall(paths), paths);\n  try {\n    await restartActiveService(rolledBack.version);\n  } catch (restartError) {\n    throw new Error(\n      `${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}, but the rolled-back service also failed to restart.`,\n      { cause: new AggregateError([validationError, restartError]) },\n    );\n  }\n  throw new Error(`${payloadLabel} failed service validation and was rolled back to ${rolledBack.version}.`, { cause: validationError });\n}\n\nexport async function updateCommand(options: UpdateOptions, overrides: Partial<Dependencies> = {}): Promise<void> {\n  const paths = overrides.paths ?? resolveInstallStorePaths();\n  const executablePath = overrides.executablePath ?? process.argv[1] ?? \"\";\n  const runCommand = overrides.runCommand ?? execFileAsync;\n  const mode = detectInstallMode(executablePath, paths);\n  const manifest = readInstallManifest(paths);\n  if (options.rollback) {\n    if (mode !== \"managed\") throw new Error(\"--rollback is only available for managed installs.\");\n    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; }\n    const next = await withInstallStoreLock(async () => rollbackManagedInstall(paths), paths);\n    const restarted = await (overrides.restartActiveService ?? restartActiveManagedService)(next.version);\n    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.`));\n    return;\n  }\n  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; }\n  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; }","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/update.ts#L146-L182","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the `cause` error to identify why the new payload failed to start, then fix or report it.","Confirm the rolled-back service is healthy: `paperclipai service status`.","Pin to the working version with `paperclipai update --version <rolled-back-version>` until the new release is fixed.","If the cause is a half-applied DB migration, restore the pre-update backup before retrying the update."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await updateCommand(options);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('failed service validation and was rolled back')) {\n    // system is back on the old version — inspect error.cause to diagnose the new payload\n    console.error('New payload failed:', error.cause);\n    // optionally pin to the rolled-back version explicitly\n  } else throw error;\n}","preventionTips":["Inspect the attached `cause` to find why the new payload failed before retrying.","Run `paperclipai update --check` first to detect obvious issues.","Keep the pre-update backup so you can recover if the rolled-back version is later found incompatible."],"tags":["rollback","service-validation","update"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}