ruvnet/ruflo · error · Error

WebSocket transport requires host and port configuration

Error message

WebSocket transport requires host and port configuration

What it means

createTransport('websocket', logger, config) mirrors the http branch: it requires host and port keys to be present in config before creating the WebSocketTransport, and throws this error otherwise. The path (default '/ws') is optional; only the address and port are mandatory. Like the http guard it checks key presence, not value validity.

Source

Thrown at v3/@claude-flow/mcp/src/transport/index.ts:52

  config?: Partial<TransportConfig>
): ITransport {
  switch (type) {
    case 'stdio':
      return createStdioTransport(logger, config as StdioTransportConfig);

    case 'http':
      if (!config || !('host' in config) || !('port' in config)) {
        throw new Error('HTTP transport requires host and port configuration');
      }
      return createHttpTransport(logger, {
        host: config.host as string,
        port: config.port as number,
        ...config,
      } as HttpTransportConfig);

    case 'websocket':
      if (!config || !('host' in config) || !('port' in config)) {
        throw new Error('WebSocket transport requires host and port configuration');
      }
      return createWebSocketTransport(logger, {
        host: config.host as string,
        port: config.port as number,
        ...config,
      } as WebSocketTransportConfig);

    case 'in-process':
      return createInProcessTransport(logger);

    default:
      throw new Error(`Unknown transport type: ${type}`);
  }
}

class InProcessTransport implements ITransport {
  public readonly type: TransportType = 'in-process';

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Pass explicit values: createTransport('websocket', logger, { host: '127.0.0.1', port: 3001, path: '/ws' })
2. Default env-derived values: host: process.env.WS_HOST ?? '127.0.0.1', port: Number(process.env.WS_PORT ?? 3001)
3. Call createWebSocketTransport(logger, cfg) directly so TypeScript enforces WebSocketTransportConfig

Example fix

// before
const t = createTransport('websocket', logger, wsConfig as any);

// after
const t = createTransport('websocket', logger, {
  host: process.env.WS_HOST ?? '127.0.0.1',
  port: Number(process.env.WS_PORT ?? 3001),
  path: '/ws',
});

const wsCfg = {
  host: process.env.WS_HOST ?? '127.0.0.1',
  port: Number(process.env.WS_PORT ?? 3001),
  path: '/ws',
};
if (!('host' in wsCfg) || !('port' in wsCfg)) {
  throw new Error('WebSocket transport config incomplete');
}
const t = createTransport('websocket', logger, wsCfg);

function isWebSocketConfig(c: unknown): c is { host: string; port: number; path?: string } {
  return (
    !!c && typeof c === 'object' &&
    'host' in c && typeof (c as { host: unknown }).host === 'string' &&
    'port' in c && typeof (c as { port: unknown }).port === 'number'
  );
}

When it happens

Trigger: Calling createTransport('websocket', logger) with no config; building config from env where WS_HOST/WS_PORT are unset; passing a config object typed for stdio (inputStream/outputStream) into the websocket branch.

Common situations: WebSocket fan-out configured via environment variables that differ per environment; sharing one Partial<TransportConfig> across several transport types; CI pipelines missing the WS section of config.

Related errors

• WebSocket transport requires host and port configuration
• HTTP transport requires host and port configuration
• Unknown transport type: ${type}
• HTTP transport requires host and port configuration
• Unknown transport type: ${type}

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/8d46ad906b1003e9. Report an issue: GitHub.