paperclipai/paperclip · error · Error

Handler function is required when a filter is provided

Error message

Handler function is required when a filter is provided

What it means

API-contract guard in event bus subscribe: the two-argument form was used where the first argument is a filter object, so the third parameter (the handler function) is undefined. Callers must pass either (pattern, fn) or (pattern, filter, fn); the malformed subscribe call is at fault.

Source

Thrown at server/src/services/plugin-event-bus.ts:234

       * For wildcard subscriptions use a trailing `.*` pattern, e.g.
       * `"plugin.acme.linear.*"`.
       *
       * Requires the `events.subscribe` capability (capability enforcement is
       * done by the host layer before calling this method).
       */
      subscribe(
        eventPattern: PluginEventType | `plugin.${string}`,
        fnOrFilter: EventFilter | ((event: PluginEvent) => Promise<void>),
        maybeFn?: (event: PluginEvent) => Promise<void>,
      ): void {
        let filter: EventFilter | null = null;
        let handler: (event: PluginEvent) => Promise<void>;

        if (typeof fnOrFilter === "function") {
          handler = fnOrFilter;
        } else {
          filter = fnOrFilter;
          if (!maybeFn) throw new Error("Handler function is required when a filter is provided");
          handler = maybeFn;
        }

        subsFor(pluginId).push({ eventPattern, filter, handler });
      },

      /**
       * Emit a plugin-namespaced event. The event type is automatically
       * prefixed with `plugin.<pluginId>.` so:
       * - `emit("sync-done", payload)` becomes `"plugin.acme.linear.sync-done"`.
       *
       * Requires the `events.emit` capability (enforced by the host layer).
       *
       * @throws {Error} if `name` already contains the `plugin.` prefix
       *   (prevents cross-namespace spoofing).
       */
      async emit(name: string, companyId: string, payload: unknown): Promise<PluginEventBusEmitResult> {
        if (!name || name.trim() === "") {

View on GitHub (pinned to 120ae5428f)

Solutions

1. Provide a handler function when subscribing with a filter, or remove the filter.

When it happens

Trigger: Thrown at server/src/services/plugin-event-bus.ts:234 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/d1672c9f52ce203c. Report an issue: GitHub.