What causes "Unsupported broker endpoint: ${endpoint}" in openai/codex-plugin-cc?

Prefix filesystem socket paths with 'unix:' and named pipes with 'pipe:'.

openai/codex-plugin-cc · error · Error

Unsupported broker endpoint: ${endpoint}

Error message

Unsupported broker endpoint: ${endpoint}

What it means

Thrown by parseBrokerEndpoint when the endpoint string does not begin with either the 'pipe:' or 'unix:' scheme. The parser only knows these two transports (Windows named pipe and POSIX unix socket), so any other prefix is unparseable.

Source

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

  }

  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 };
  }

  throw new Error(`Unsupported broker endpoint: ${endpoint}`);
}

View on GitHub (pinned to db52e28f4d)

Solutions

Prefix filesystem socket paths with 'unix:' and named pipes with 'pipe:'.
If you need TCP transport, that is unsupported by this runtime; remove the custom endpoint and let createBrokerEndpoint pick a local socket/pipe.
Trim whitespace and strip BOM from the endpoint string before parsing.
Always obtain endpoints from createBrokerEndpoint rather than constructing scheme strings by hand.

Example fix

// before
parseBrokerEndpoint('/tmp/codex/broker.sock') // throws (no scheme)
parseBrokerEndpoint('tcp://127.0.0.1:8080') // throws (unsupported scheme)

// after
parseBrokerEndpoint('unix:/tmp/codex/broker.sock')

Defensive patterns

Strategy: validation

Validate before calling

const BROKER_SCHEMES = ['unix:', 'pipe:'];
function hasSupportedScheme(endpoint) {
  return typeof endpoint === 'string' &&
    BROKER_SCHEMES.some((s) => endpoint.startsWith(s));
}
// call: if (!hasSupportedScheme(endpoint)) throw new Error('Use createBrokerEndpoint to produce a valid endpoint');

Type guard

null

Try / catch

null

Prevention

Only accept endpoints produced by createBrokerEndpoint.
Do not attempt TCP/HTTP/ws transports; they are unsupported by this runtime.
Trim whitespace and strip BOM from config-supplied endpoints before parsing.
Document that the only valid schemes are 'unix:' and 'pipe:'.

When it happens

Trigger: Calling parseBrokerEndpoint with a value like 'tcp://127.0.0.1:8080', 'http://...', 'ws://...', or a bare path '/tmp/broker.sock' (missing the 'unix:' scheme). Also triggered by typos like 'unixs:' or 'pipe =' with a space.

Common situations: A user tried to force a TCP/HTTP broker transport that the runtime does not support. Copy-pasting an endpoint from a different tool. A leading space or BOM character breaks the startsWith checks.

Related errors

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