paperclipai/paperclip · error

${agent.orgChainHealth?.repairGuidance ?? "Repair this agent

Error message

${agent.orgChainHealth?.repairGuidance ?? "Repair this agent's reporting chain before starting runs"}

What it means

Org-health conflict guard in the wakeup route helper: a run cannot be started because the agent's reporting chain is invalid (orgChainHealth 'invalid_org_chain'); the 409 carries the agent's specific repair guidance so the operator fixes the chain before running work.

Source

Thrown at server/src/routes/agents.ts:4809

    const id = req.params.id as string;
    const existing = await getAccessibleResource(req, res, svc.getById(id), "Agent not found");
    if (!existing) return;

    if (hasOwn(req.body as object, "permissions")) {
      res.status(422).json({ error: "Use /api/agents/:id/permissions for permission changes" });
      return;
    }

    const patchData = { ...(req.body as Record<string, unknown>) };
    const replaceAdapterConfig = patchData.replaceAdapterConfig === true;
    delete patchData.replaceAdapterConfig;
    // The apply-existing flag is not an agent column. The server binds the fixed
    // reference to the owner stored value with no login round trip. Remove it
    // from the patch so it never reaches the update values.
    const applyStoredClaudeLogin = patchData.applyStoredClaudeLogin === true;
    delete patchData.applyStoredClaudeLogin;
    if (hasOwn(patchData, "adapterConfig")) {
      const adapterConfig = asRecord(patchData.adapterConfig);
      if (!adapterConfig) {
        res.status(422).json({ error: "adapterConfig must be an object" });
        return;
      }
      assertNoAgentAdapterConfigMutation(req, adapterConfig);
      const changingInstructionsConfig = adapterConfigTouchesInstructionsConfig(adapterConfig);
      if (changingInstructionsConfig) {
        await assertCanManageInstructionsPath(req, existing);
      }
      patchData.adapterConfig = adapterConfig;
    }

    // Switching an existing agent ONTO another adapter is a new selection, so
    // it gets the selectable check; keeping the agent's current adapter (even
    // one since disabled) stays allowed, so a disabled harness does not make an
    // existing agent uneditable.
    const nextAdapterType = hasOwn(patchData, "adapterType")
      ? assertKnownAdapterType(patchData.adapterType as string | null | undefined)

View on GitHub (pinned to 01ad858492)

Solutions

1. Repair the agent's reporting chain per the repair guidance, then start runs.

When it happens

Trigger: Thrown at server/src/routes/agents.ts:4264 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/a0f11e78562a9c4c. Report an issue: GitHub.