paperclipai/paperclip · error · HttpError

review_required

review_required

Error message

Stage approval requires a human approver

What it means

Governance guard in assertActorCanApproveStageExit: the stage's config requires approval (requireApproval=true) but the resolved approver is not a human actor. Automation/agent actors cannot satisfy a human-approval gate, so the stage-exit approval is rejected.

Source

Thrown at server/src/services/pipelines.ts:1067

function assertStageEnabled(stage: typeof pipelineStages.$inferSelect, action: string) {
  const config = normalizeStageConfig(stage.kind, stageConfig(stage));
  if (config.disabled !== true) return;
  throw unprocessable("Pipeline stage is disabled", {
    code: "stage_disabled",
    action,
    stageId: stage.id,
    stageKey: stage.key,
  });
}

function assertActorCanApproveStageExit(stage: typeof pipelineStages.$inferSelect, actor: PipelineActor) {
  const config = normalizeStageConfig(stage.kind, stageConfig(stage));
  if (config.requireApproval !== true) return;
  const approver = config.approver ?? { kind: "any_human" };
  if (approver.kind === "any_human") {
    if (actor.type === "user") return;
    throw new HttpError(403, "Stage approval requires a human approver", { code: "review_required" });
  }
  if (approver.kind === "user") {
    if (actor.type === "user" && actor.userId === approver.id) return;
    throw new HttpError(403, "Stage approval requires the configured user approver", {
      code: "review_required",
      approver,
    });
  }
  if (actor.type === "agent" && actor.agentId === approver.id) return;
  throw new HttpError(403, "Stage approval requires the configured agent approver", {
    code: "review_required",
    approver,
  });
}

function assertReviewTargetsInSet(
  kind: PipelineStageKind | string,
  config: PipelineStageConfig,

View on GitHub (pinned to 120ae5428f)

Solutions

1. Approve the stage as a human user; agent actors cannot approve this stage.

When it happens

Trigger: Thrown at server/src/services/pipelines.ts:1067 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/3968e6fcdef13320. Report an issue: GitHub.