openai/codex-plugin-cc · error · Error

codex app-server broker connection is not connected.

Error message

codex app-server broker connection is not connected.

What it means

BrokerCodexAppServerClient.sendMessage writes to this.socket. If the socket is null/undefined (sendMessage called before initialize() created it, or after close() where socket.end() was called and the reference cleared on a subsequent path), it throws. This guards the broker transport the same way the spawned client guards stdin.

Source

Thrown at plugins/codex/scripts/lib/app-server.mjs:329

  async close() {
    if (this.closed) {
      await this.exitPromise;
      return;
    }

    this.closed = true;
    if (this.socket) {
      this.socket.end();
    }
    await this.exitPromise;
  }

  sendMessage(message) {
    const line = `${JSON.stringify(message)}\n`;
    const socket = this.socket;
    if (!socket) {
      throw new Error("codex app-server broker connection is not connected.");
    }
    socket.write(line);
  }
}

export class CodexAppServerClient {
  static async connect(cwd, options = {}) {
    let brokerEndpoint = null;
    if (!options.disableBroker) {
      brokerEndpoint = options.brokerEndpoint ?? options.env?.[BROKER_ENDPOINT_ENV] ?? process.env[BROKER_ENDPOINT_ENV] ?? null;
      if (!brokerEndpoint && options.reuseExistingBroker) {
        brokerEndpoint = loadBrokerSession(cwd)?.endpoint ?? null;
      }
      if (!brokerEndpoint && !options.reuseExistingBroker) {
        const brokerSession = await ensureBrokerSession(cwd, { env: options.env });
        brokerEndpoint = brokerSession?.endpoint ?? null;
      }
    }

View on GitHub (pinned to db52e28f4d)

Solutions

1. Await CodexAppServerClient.connect() (which awaits initialize) before sending, so the socket exists.
2. After close(), create a new client rather than reusing; do not call request on a closed broker client.
3. If the socket errored, surface handleExit and reconnect via a fresh ensureBrokerSession/client.connect.

Example fix

// before
const client = new BrokerCodexAppServerClient(cwd, { brokerEndpoint });
client.request('turn/start', params); // socket not yet connected
// after
const client = await CodexAppServerClient.connect(cwd, { brokerEndpoint });
await client.request('turn/start', params);

if (!client.socket) throw new Error('broker socket unavailable; reconnect');

/** @param {object} c @returns {boolean} */
function hasBrokerSocket(c) { return Boolean(c.socket); }

try {
  await client.request(method, params);
} catch (e) {
  if (/not connected/.test(e.message)) { /* re-establish broker session */ }
  else throw e;
}

When it happens

Trigger: Calling request() before broker initialize() resolves (socket not yet created), or after close() ended the socket. Also if the broker connection errored and the socket was torn down.

Common situations: Lifecycle race with the broker: a notification or request issued during connection teardown, or retry logic that does not re-establish the broker session.

Related errors

• codex app-server stdin is not available.
• codex app-server client is closed.
• Missing broker endpoint.
• Broker pipe endpoint is missing its path.
• Broker Unix socket endpoint is missing its path.

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/00dc8d4ce1840eb7. Report an issue: GitHub.