ruvnet/ruflo · error · Error

Unknown transport type: ${type}

Error message

Unknown transport type: ${type}

What it means

createTransport switches over the TransportType union - 'stdio', 'http', 'websocket', 'in-process' - and the default arm throws 'Unknown transport type: ${type}' for anything else. When the argument is a checked literal, TypeScript makes this unreachable; the throw is hit with dynamically-typed input (strings from env vars, CLI flags, JSON/YAML config) containing a typo, wrong casing, or a name removed/renamed across versions.

Source

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

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

/**
 * In-process transport (no-op wrapper)
 *
 * Used when tools are executed directly without network transport
 */
class InProcessTransport implements ITransport {
  public readonly type: TransportType = 'in-process';

  constructor(private readonly logger: ILogger) {}

  async start(): Promise<void> {
    this.logger.debug('In-process transport started');
  }

  async stop(): Promise<void> {

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Normalize then validate before the call: trim().toLowerCase() and check membership in ['stdio','http','websocket','in-process'], failing with a message listing valid values
2. Fix the typo/casing at the config source
3. If the name came from an upgrade, check the changelog and migrate to a supported transport type

Example fix

// before
const type = process.env.MCP_TRANSPORT as TransportType; // 'HTTP'
const t = createTransport(type, logger, cfg); // throws: Unknown transport type: HTTP

// after
const TYPES = ['stdio', 'http', 'websocket', 'in-process'] as const;
const raw = (process.env.MCP_TRANSPORT ?? 'stdio').trim().toLowerCase();
if (!TYPES.includes(raw as any)) {
  throw new Error(`Unsupported transport '${raw}'. Supported: ${TYPES.join(', ')}`);
}
const t = createTransport(raw as TransportType, logger, cfg);

const raw = (source as string | undefined)?.trim().toLowerCase();
if (!isTransportType(raw)) {
  throw new Error(`Unsupported transport '${raw}'. Supported: ${TRANSPORT_TYPES.join(', ')}`);
}
return createTransport(raw, logger, config);

const TRANSPORT_TYPES = ['stdio', 'http', 'websocket', 'in-process'] as const;
type TransportType = typeof TRANSPORT_TYPES[number];
function isTransportType(v: unknown): v is TransportType {
  return typeof v === 'string' && (TRANSPORT_TYPES as readonly string[]).includes(v);
}

try {
  return createTransport(type as TransportType, logger, config);
} catch (e) {
  if (e instanceof Error && /Unknown transport type/.test(e.message)) {
    console.error(`Supported transports: ${TRANSPORT_TYPES.join(', ')}`);
    process.exit(2); // config error: fail fast with guidance
  }
  throw e;
}

When it happens

Trigger: createTransport(process.env.MCP_TRANSPORT as TransportType, ...) where the value is 'HTTP' (case-sensitive switch) or 'tcp'; config YAML with 'socket' instead of 'stdio'; stale config still naming a transport type that a newer library version removed or renamed; JSON parsed as any and passed through unchecked.

Common situations: Env/CLI-driven transport selection without normalization; config files authored against an older release; casing mismatches like 'WebSocket' vs 'websocket'; users guessing supported values with no up-front validation.

Related errors

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