ruvnet/ruflo · error

WebSocket transport requires host and port configuration

Error message

WebSocket transport requires host and port configuration

What it means

createTransport('websocket', logger, config) requires a config object containing host and port keys - the same key-presence check as the http case. The WebSocket transport later binds host, port and an optional path (default '/ws'), so without a host/port pair there is nothing sensible to construct. Missing config or a config without both keys throws from the factory before any socket is created.

Source

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

  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':
      // In-process transport is handled directly by the server
      // Return a no-op transport wrapper
      return createInProcessTransport(logger);

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

/**

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Pass explicit config: createTransport('websocket', logger, { host: '0.0.0.0', port: 8081, path: '/ws' })
2. Type the config as WebSocketTransportConfig at the call site so TypeScript enforces host/port
3. Validate config once at startup (presence AND value checks) and fail fast naming the missing field

Example fix

// before
const t = createTransport('websocket', logger, { path: '/ws' }); // no host/port

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

if (!hasHostPort(config)) {
  throw new Error('WebSocket transport config must provide host and port (path defaults to /ws)');
}
return createTransport('websocket', logger, config);

function hasHostPort(c?: Partial<TransportConfig>): c is { host: string; port: number } {
  return !!c
    && typeof (c as { host?: unknown }).host === 'string'
    && (c as { host?: unknown }).host.length > 0
    && typeof (c as { port?: unknown }).port === 'number';
}

try {
  return createTransport('websocket', logger, cfg);
} catch (e) {
  if (e instanceof Error && /host and port/.test(e.message)) {
    throw new ConfigError('WebSocket host/port missing in config');
  }
  throw e;
}

When it happens

Trigger: createTransport('websocket', logger) with no config; a config object typed Partial<TransportConfig> that only carries stdio-ish fields; conditional spread building config that omits host/port when a flag is off; env vars for host/port unset so keys are never written.

Common situations: Migrating a stdio-based CLI to a websocket listener without adding network config; YAML/JSON config written for http then reused for websocket minus one field; default-path assumption ('path only') while host/port were never supplied.

Related errors

• HTTP transport requires host and port configuration
• WebSocket 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/0eac5fd958f8fe7b. Report an issue: GitHub.