{"record":{"id":"1dc6e3d1e0144a00","repo":"mastra-ai/mastra","slug":"unixsocketpubsub-does-not-support-grouped-subscrip","errorCode":null,"errorMessage":"UnixSocketPubSub does not support grouped subscriptions yet","messagePattern":"UnixSocketPubSub does not support grouped subscriptions yet","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/events/unix-socket-pubsub.ts","lineNumber":219,"sourceCode":"      this.#deliverLocal(topic, localEvent);\n      return;\n    }\n\n    if (this.#isBroker) {\n      await this.#publishFromBroker(topic, event, undefined, options?.localOnly);\n      return;\n    }\n\n    const socket = this.#clientSocket;\n    if (!socket || socket.destroyed) {\n      await this.#ensureStarted(true);\n    }\n    await this.#sendToBroker({ type: 'publish', topic, event, localOnly: options?.localOnly });\n  }\n\n  async subscribe(topic: string, cb: EventCallback, options?: SubscribeOptions): Promise<void> {\n    if (options?.group) {\n      throw new Error('UnixSocketPubSub does not support grouped subscriptions yet');\n    }\n\n    const callbacks = this.#callbacks.get(topic) ?? new Set<EventCallback>();\n    const hadCallback = callbacks.has(cb);\n    const wasConnected = Boolean(this.#clientSocket && !this.#clientSocket.destroyed);\n    callbacks.add(cb);\n    this.#callbacks.set(topic, callbacks);\n\n    try {\n      await this.#ensureStarted();\n      if (!this.#isBroker && !hadCallback && wasConnected) {\n        await this.#sendSubscribeToBroker(topic);\n      }\n    } catch (error) {\n      if (!hadCallback) {\n        callbacks.delete(cb);\n        if (callbacks.size === 0) {\n          this.#callbacks.delete(topic);","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/events/unix-socket-pubsub.ts#L201-L237","documentation":"UnixSocketPubSub does not implement consumer-group semantics, where multiple subscribers share messages from a topic. Passing options.group to subscribe() throws immediately rather than silently ignoring the grouping option.","triggerScenarios":"Calling pubsub.subscribe(topic, callback, { group: \"workers\" }) — any non-empty group option in SubscribeOptions on a UnixSocketPubSub instance, typically from setupPair.","commonSituations":"Code shared between a pubsub backend that supports groups (e.g. Redis-based) and this Unix-socket backend, load-balancing multiple workers over one topic, copy-pasted subscription code.","solutions":["Remove the group option and subscribe without it","If load balancing is required, switch to a pubsub implementation that supports grouped subscriptions","Implement app-level fan-out partitioning (e.g. route by event key in your own callback)","Check the backend's feature matrix before relying on group semantics"],"exampleFix":"// before\nawait pubsub.subscribe(\"jobs\", handler, { group: \"workers\" });\n// after\nawait pubsub.subscribe(\"jobs\", handler);","handlingStrategy":"fallback","validationCode":"if ('group' in options && options.group) {\n  throw new Error('Backend does not support grouped subscriptions');\n}\nawait pubsub.subscribe(topic, cb);","typeGuard":null,"tryCatchPattern":"try {\n  await pubsub.subscribe(topic, cb, options);\n} catch (e) {\n  if (e.message.includes('grouped subscriptions')) {\n    await pubsub.subscribe(topic, cb); // fall back to ungrouped\n  } else throw e;\n}","preventionTips":["Check backend capability before passing SubscribeOptions.group","Abstract subscriptions behind an interface that only exposes group on supporting backends","Add a unit test asserting group options are only sent to group-capable pubsub implementations","Document group support per pubsub backend in your infra docs"],"tags":["pubsub","unix-socket","unsupported-feature"],"backgroundTag":"grouped-subscription-unsupported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}