ruvnet/ruflo · error

HTTP transport requires host and port configuration

Error message

HTTP transport requires host and port configuration

What it means

createTransport('http', logger, config) requires a config object containing host and port keys. The factory does a key-presence check (!('host' in config) || !('port' in config)) before constructing the HTTP transport, because a network listener has no usable defaults (unlike stdio, which falls back to process.stdin/stdout). Missing config or a config lacking either key throws immediately. Note the guard checks key presence, not values: { host: undefined, port: undefined } passes here but fails later at bind time.

Source

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

  | { type: 'http' } & HttpTransportConfig
  | { type: 'websocket' } & WebSocketTransportConfig
  | { type: 'in-process' };

/**
 * Create a transport instance based on type
 */
export function createTransport(
  type: TransportType,
  logger: ILogger,
  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':

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Pass an explicit literal config: createTransport('http', logger, { host: '127.0.0.1', port: 8080 })
2. Type the call site with HttpTransportConfig (not Partial<TransportConfig>) so missing keys become a compile error
3. Parse and validate env/config once at boot with named-variable error messages before any transport is created
4. Also validate values (non-empty host, numeric port in range), since presence alone is not enough

Example fix

// before
const cfg: Partial<TransportConfig> = loadOptionalConfig(); // may lack port
const t = createTransport('http', logger, cfg); // throws

// after
const host = requireEnv('MCP_HOST');
const port = requirePort('MCP_PORT');
const t = createTransport('http', logger, { host, port });

if (!hasHostPort(config)) {
  throw new Error('HTTP transport config must provide MCP_HOST and MCP_PORT');
}
return createTransport('http', 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('http', logger, cfg);
} catch (e) {
  if (e instanceof Error && /host and port/.test(e.message)) {
    throw new ConfigError('MCP_HOST / MCP_PORT missing or unset');
  }
  throw e;
}

When it happens

Trigger: createTransport('http', logger) with the third argument omitted; reusing a Partial<TransportConfig> built for stdio when switching type to 'http'; a helper that builds config via conditional spread that drops the keys; env-driven config where MCP_HOST/MCP_PORT are unset so keys never get assigned.

Common situations: Switching the default transport from stdio to http without adding config plumbing; config assembled from optional env vars; refactors that destructure/spread config through layers and lose fields; TypeScript silence because the arg is typed Partial<TransportConfig>.

Related errors

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

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