What causes "UnixSocketPubSub is not connected to a broker" in mastra-ai/mastra?

Ensure connect() is awaited and completed before calling publish or subscribe

UnixSocketPubSub is not connected to a broker

Error message

UnixSocketPubSub is not connected to a broker

What it means

UnixSocketPubSub publishes/subscribes over a local Unix domain socket broker. publish() (and similar send paths) checks the internal client socket before writing; if the socket was never connected or has been destroyed, the library throws this error rather than silently dropping the message. It is an internal invariant guard that doubles as a signal for the transient-error classifier in #sendToBroker.

Source

Thrown at packages/core/src/events/unix-socket-pubsub.ts:760

        await new Promise(resolve => setTimeout(resolve, 10 * (attempt + 1)));
      }
    }
  }

  async #sendToActiveBroker(frame: ClientFrame) {
    const socket = this.#clientSocket;
    if (!socket || socket.destroyed) {
      await this.#ensureStarted(true);
    }
    if (this.#isBroker) {
      await this.#handlePromotedBrokerFrame(frame);
      return;
    }
    const activeSocket = this.#clientSocket;
    if (!activeSocket || activeSocket.destroyed) {
      // NOTE: keep this exact message in sync with the transient-error
      // classifier in #sendToBroker (search for 'not connected to a broker').
      throw new Error('UnixSocketPubSub is not connected to a broker');
    }
    await writeFrame(activeSocket, frame);
  }

  async #handlePromotedBrokerFrame(frame: ClientFrame) {
    if (frame.type === 'subscribe') {
      this.#settleSubscribeWaiters(frame.topic);
    } else if (frame.type === 'publish') {
      await this.#publishFromBroker(frame.topic, frame.event);
    }
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure connect() is awaited and completed before calling publish or subscribe
Add reconnect logic: catch this error, call connect() again, then retry the publish
Check broker/socket lifecycle — make sure the broker process is running and the socket path is valid
If publishing on shutdown, guard calls with a connected-state check on the instance

Example fix

// before
await pubsub.publish({ topic: 'events', data });
// after
if (!pubsub.isConnected()) {
  await pubsub.connect();
}
await pubsub.publish({ topic: 'events', data });

Defensive patterns

Strategy: retry

Validate before calling

function canPublish(pubsub) {
  return pubsub.isConnected?.() === true;
}

Type guard

function isSocketLive(socket) {
  return socket != null && !socket.destroyed;
}

Try / catch

try {
  await pubsub.publish(frame);
} catch (e) {
  if (e.message.includes('not connected to a broker')) {
    await pubsub.connect();
    await pubsub.publish(frame);
  } else {
    throw e;
  }
}

Prevention

Always await connect() before first publish
Add reconnect-with-backoff on socket close/destroy events
Suppress publishes during shutdown once disconnect() has been called
In tests, start the broker fixture before instantiating the pub/sub client

When it happens

Trigger: Calling publish/subscribe on a UnixSocketPubSub instance whose #clientSocket is undefined or has .destroyed set — e.g. calling publish() before connect() completes, after the broker process exited and killed the socket, or after an explicit disconnect().

Common situations: Publishing during application startup before the pub/sub client has finished connecting; a crashed broker daemon leaving a destroyed socket; unit tests instantiating UnixSocketPubSub without a running broker; race between broker restart and in-flight publish calls.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/313dcbeff789c539. Report an issue: GitHub.