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.

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.
• Broker pipe endpoint is missing its path.
• Broker Unix socket endpoint is missing its path.
• codex app-server client is closed.
• Missing broker endpoint.

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

Appendix: 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)