paperclipai/paperclip · error

hasPlanDocument must be true or false when provided

Error message

hasPlanDocument must be true or false when provided

What it means

400 from the issue list route: the hasPlanDocument boolean query parameter failed to parse as true or false (parseOptionalBooleanQuery returned null).

Source

Thrown at server/src/routes/issues.ts:6170

  // Reopen the closed isolated workspace that a guard found, so the request can
  // continue. The return value tells the caller what happened:
  //   "reopened"    - this request rebuilt the workspace and set the
  //                   reopen-pending flag. The caller must install the
  //                   consumption guard so the flag cannot leak.
  //   "already-open" - a concurrent request already reopened the workspace, so
  //                   this request did not set the flag. The caller continues but
  //                   must not install the guard, or it can clear the flag that
  //                   the other request still owns.
  //   null          - this function sent an error response, so the caller stops.
  // The reopen is scoped to the issue company and project inside the service, and
  // it runs only after the route already authorized the request on the issue.
  async function reopenClosedIssueExecutionWorkspaceOrRespond(
    req: Request,
    res: Response,
    issue: { id: string; companyId: string; projectId?: string | null },
    workspace: Pick<ExecutionWorkspace, "id">,
  ): Promise<{ outcome: "reopened" | "already-open"; generation: number } | null> {
    const actor = getActorInfo(req);
    const result = await executionWorkspacesSvc.reopenClosedIsolatedExecutionWorkspaceForIssue({
      workspaceId: workspace.id,
      issue: { id: issue.id, companyId: issue.companyId, projectId: issue.projectId ?? null },
      actor: { agentId: actor.agentId, actorType: actor.actorType },
    });
    if (result.ok) {
      return { outcome: result.reopened ? "reopened" : "already-open", generation: result.generation };
    }
    if (result.code === "not_reopenable") {
      res.status(409).json({ error: "This issue is linked to a closed workspace that cannot be reopened." });
    } else {
      res.status(503).json({ error: "Could not reopen the workspace for this issue. Please try again." });
    }
    return null;
  }

  // The keepalive re-stamps the reopen-pending flag on this interval while a
  // consuming request is in flight. The interval is one fifth of the stale grace

View on GitHub (pinned to 01ad858492)

Solutions

1. Fix the offending parameter to satisfy the constraint stated in the error message (type, range, or allowed values), then retry.
2. Refer to the route's request validation in the named file and the shared validators for the accepted format.

When it happens

Trigger: Thrown at server/src/routes/issues.ts:5864 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/fa9714cd85027412. Report an issue: GitHub.