paperclipai/paperclip · error

Agent wakeup was skipped by heartbeat policy

Error message

Agent wakeup was skipped by heartbeat policy

What it means

The heartbeat wakeup() call for an agent was suppressed by heartbeat policy (e.g. rate limits, paused agent, or cooldown), so the requested automation wakeup did not dispatch. The result is surfaced as an error so the plugin knows nothing was woken.

Source

Thrown at server/src/services/plugin-host-services.ts:2830

        const agent = await agents.getById(params.agentId);
        requireInCompany("Agent", agent, companyId);
        const run = await heartbeat.wakeup(params.agentId, {
          source: "automation",
          triggerDetail: "system",
          reason: params.reason ?? null,
          payload: { prompt: params.prompt },
          contextSnapshot: {
            wakeReason: params.reason ?? null,
            paperclipAgentMessage: {
              text: params.prompt,
              source: "plugin_invoke",
              pluginKey,
            },
          },
          requestedByActorType: "system",
          requestedByActorId: pluginId,
        });
        if (!run) throw new Error("Agent wakeup was skipped by heartbeat policy");
        return { runId: run.id };
      },
      async managedGet(params) {
        const companyId = ensureCompanyId(params.companyId);
        await ensurePluginAvailableForCompany(companyId);
        return managedAgents.get(params.agentKey, companyId);
      },
      async managedReconcile(params) {
        const companyId = ensureCompanyId(params.companyId);
        await ensurePluginAvailableForCompany(companyId);
        return managedAgents.reconcile(params.agentKey, companyId);
      },
      async managedReset(params) {
        const companyId = ensureCompanyId(params.companyId);
        await ensurePluginAvailableForCompany(companyId);
        return managedAgents.reset(params.agentKey, companyId);
      },
    },

View on GitHub (pinned to a7e689b3c3)

Solutions

1. This is an informational outcome: the heartbeat policy declined the wakeup. Adjust the agent's heartbeat/wake policy settings or wait for the next eligible wake window.

When it happens

Trigger: Thrown at server/src/services/plugin-host-services.ts:2821 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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