openai/codex-plugin-cc · error · Error

Missing broker endpoint.

Error message

Missing broker endpoint.

What it means

Thrown by parseBrokerEndpoint when the endpoint argument is not a non-empty string. parseBrokerEndpoint is the inverse of createBrokerEndpoint: it decodes a 'pipe:' or 'unix:' URI back into {kind, path}. A missing/empty endpoint means the broker session configuration was never written or was corrupted, so no transport can be selected.

Source

Thrown at plugins/codex/scripts/lib/broker-endpoint.mjs:21

function sanitizePipeName(value) {
  return String(value ?? "")
    .replace(/[^A-Za-z0-9._-]/g, "-")
    .replace(/^-+|-+$/g, "");
}

export function createBrokerEndpoint(sessionDir, platform = process.platform) {
  if (platform === "win32") {
    const pipeName = sanitizePipeName(`${path.win32.basename(sessionDir)}-codex-app-server`);
    return `pipe:\\\\.\\pipe\\${pipeName}`;
  }

  return `unix:${path.join(sessionDir, "broker.sock")}`;
}

export function parseBrokerEndpoint(endpoint) {
  if (typeof endpoint !== "string" || endpoint.length === 0) {
    throw new Error("Missing broker endpoint.");
  }

  if (endpoint.startsWith("pipe:")) {
    const pipePath = endpoint.slice("pipe:".length);
    if (!pipePath) {
      throw new Error("Broker pipe endpoint is missing its path.");
    }
    return { kind: "pipe", path: pipePath };
  }

  if (endpoint.startsWith("unix:")) {
    const socketPath = endpoint.slice("unix:".length);
    if (!socketPath) {
      throw new Error("Broker Unix socket endpoint is missing its path.");
    }
    return { kind: "unix", path: socketPath };
  }

View on GitHub (pinned to db52e28f4d)

Solutions

1. Ensure createBrokerEndpoint(sessionDir) ran and its return value was stored/passed to parseBrokerEndpoint.
2. Set the broker endpoint env var to a valid 'unix:/path/to/broker.sock' or 'pipe:\\.\pipe\name' string before parsing.
3. Guard the caller: if endpoint is falsy, call createBrokerEndpoint(cwd) to synthesize one rather than parsing.
4. Check that loadBrokerSession(cwd) actually wrote the session file and that it contains the endpoint field.

Example fix

// before
const transport = parseBrokerEndpoint(loadedEndpoint) // loadedEndpoint is undefined -> throws

// after
const endpoint = loadedEndpoint || createBrokerEndpoint(sessionDir)
const transport = parseBrokerEndpoint(endpoint)

import { createBrokerEndpoint } from './broker-endpoint.mjs';

function safeParseBrokerEndpoint(endpoint, sessionDir, platform) {
  if (typeof endpoint !== 'string' || endpoint.length === 0) {
    // synthesize a fresh endpoint instead of throwing
    endpoint = createBrokerEndpoint(sessionDir, platform);
  }
  return parseBrokerEndpoint(endpoint);
}

function isBrokerEndpointString(v) {
  return typeof v === 'string' && v.length > 0 && (v.startsWith('unix:') || v.startsWith('pipe:'));
}

null

When it happens

Trigger: Calling parseBrokerEndpoint(undefined), parseBrokerEndpoint(''), or parseBrokerEndpoint(null). This happens when the CODEX broker endpoint env var is unset, loadBrokerSession(cwd) returned null, and a caller forwarded that null/empty value into the parser instead of falling back to createBrokerEndpoint.

Common situations: First run in a fresh session dir before any broker.sock was created. An env var (e.g. BROKER_ENDPOINT_ENV) was cleared or never exported. A stale config file pointed to an endpoint that got overwritten with empty. Cross-platform code passing a win32 pipe on a unix host or vice-versa without normalizing first.

Related errors

• Broker pipe endpoint is missing its path.
• Broker Unix socket endpoint is missing its path.
• Unsupported broker endpoint: ${endpoint}
• codex app-server broker connection is not connected.
• Unsupported review scope "${requestedScope}". Use one of: au

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