danny-avila/LibreChat · error · AgentRunEnvelopeError

Unsupported agent run protocol: ${receivedProtocol}

Error message

Unsupported agent run protocol: ${receivedProtocol}

What it means

Thrown by createAgentRunEnvelope when input.protocol is neither 'chat.completions' nor 'responses'. The two earlier if-branches handle the valid protocols; anything that falls through reaches this terminal throw. At the type level the union should prevent this, so at runtime it indicates a value that escaped TypeScript narrowing (any-cast, untyped input, or a typo).

Source

Thrown at packages/api/src/agents/envelope.ts:248

  };

  if (input.protocol === 'chat.completions') {
    return {
      ...base,
      protocol: input.protocol,
      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),
    };
  }

  if (input.protocol === 'responses') {
    return {
      ...base,
      protocol: input.protocol,
      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),
    };
  }

  throw new AgentRunEnvelopeError(`Unsupported agent run protocol: ${receivedProtocol}`);
}

View on GitHub (pinned to 5ff282f900)

Solutions

1. Hard-code the literal: protocol: 'chat.completions' or protocol: 'responses' — match exactly.
2. Validate the source string against the allowed set before calling: if (!['chat.completions','responses'].includes(p)) throw.
3. Remove any `as any`/`as AgentRunProtocol` casts on the protocol value.

Example fix

// before
const env = createAgentRunEnvelope({ protocol: config.mode as any, requestId, receivedAt, principal, payload });

// after
const protocol = config.mode === 'responses' ? 'responses' : 'chat.completions';
const env = createAgentRunEnvelope({ protocol, requestId, receivedAt, principal, payload });

const PROTOCOLS = ['chat.completions', 'responses'] as const;
type Protocol = (typeof PROTOCOLS)[number];
function asProtocol(value: string): Protocol {
  if (!PROTOCOLS.includes(value as Protocol)) {
    throw new Error(`Unsupported protocol: ${value}. Expected one of: ${PROTOCOLS.join(', ')}`);
  }
  return value as Protocol;
}
const env = createAgentRunEnvelope({ ...input, protocol: asProtocol(input.protocol) });

function isAgentRunProtocol(value: unknown): value is 'chat.completions' | 'responses' {
  return value === 'chat.completions' || value === 'responses';
}

try {
  const env = createAgentRunEnvelope(input);
} catch (e) {
  if (e instanceof AgentRunEnvelopeError && /Unsupported agent run protocol/.test(e.message)) {
    // map the incoming value to a supported protocol or reject the request
  } else throw e;
}

When it happens

Trigger: Passing protocol as undefined, an empty string, a typo like 'chat.completion' (singular) or 'response' (singular), or a value cast through any/from a loosely-typed config.

Common situations: Reading protocol from a config/env string without validating against the literal union; an any-typed upstream value; a copy-paste from docs using the wrong literal; a future protocol added to the type but not handled in the function.

Related errors

• receivedAt must be a non-negative integer timestamp
• Invalid principal type: ${principalType}
• ${path} must be a non-empty string
• [${req.baseUrl}] Endpoint is required
• Text is required

AI-assisted analysis of danny-avila/LibreChat@5ff282f900 (2026-08-12). Data as JSON: /api/errors/da2a8602152f78ea. Report an issue: GitHub.