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

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.

Solutions

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

Defensive patterns

Strategy: validation

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@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/a0f11e78562a9c4c. Report an issue: GitHub.

Appendix: source

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

    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 3f1d897a7c)