{"record":{"id":"da2a8602152f78ea","repo":"danny-avila/LibreChat","slug":"unsupported-agent-run-protocol-receivedprotocol","errorCode":null,"errorMessage":"Unsupported agent run protocol: ${receivedProtocol}","messagePattern":"Unsupported agent run protocol: (.+?)","errorType":"validation","errorClass":"AgentRunEnvelopeError","httpStatus":null,"severity":"error","filePath":"packages/api/src/agents/envelope.ts","lineNumber":248,"sourceCode":"  };\n\n  if (input.protocol === 'chat.completions') {\n    return {\n      ...base,\n      protocol: input.protocol,\n      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),\n    };\n  }\n\n  if (input.protocol === 'responses') {\n    return {\n      ...base,\n      protocol: input.protocol,\n      payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),\n    };\n  }\n\n  throw new AgentRunEnvelopeError(`Unsupported agent run protocol: ${receivedProtocol}`);\n}\n","sourceCodeStart":230,"sourceCodeEnd":250,"githubUrl":"https://github.com/danny-avila/LibreChat/blob/5ff282f9006c436e561de1afd39a481bea1ef0d8/packages/api/src/agents/envelope.ts#L230-L250","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Hard-code the literal: protocol: 'chat.completions' or protocol: 'responses' — match exactly.","Validate the source string against the allowed set before calling: if (!['chat.completions','responses'].includes(p)) throw.","Remove any `as any`/`as AgentRunProtocol` casts on the protocol value."],"exampleFix":"// before\nconst env = createAgentRunEnvelope({ protocol: config.mode as any, requestId, receivedAt, principal, payload });\n\n// after\nconst protocol = config.mode === 'responses' ? 'responses' : 'chat.completions';\nconst env = createAgentRunEnvelope({ protocol, requestId, receivedAt, principal, payload });","handlingStrategy":"type-guard","validationCode":"const PROTOCOLS = ['chat.completions', 'responses'] as const;\ntype Protocol = (typeof PROTOCOLS)[number];\nfunction asProtocol(value: string): Protocol {\n  if (!PROTOCOLS.includes(value as Protocol)) {\n    throw new Error(`Unsupported protocol: ${value}. Expected one of: ${PROTOCOLS.join(', ')}`);\n  }\n  return value as Protocol;\n}\nconst env = createAgentRunEnvelope({ ...input, protocol: asProtocol(input.protocol) });","typeGuard":"function isAgentRunProtocol(value: unknown): value is 'chat.completions' | 'responses' {\n  return value === 'chat.completions' || value === 'responses';\n}","tryCatchPattern":"try {\n  const env = createAgentRunEnvelope(input);\n} catch (e) {\n  if (e instanceof AgentRunEnvelopeError && /Unsupported agent run protocol/.test(e.message)) {\n    // map the incoming value to a supported protocol or reject the request\n  } else throw e;\n}","preventionTips":["Type the source as the literal union; never `as any` a protocol value.","Validate config/env-derived protocol strings against the allowed set at startup.","Add an exhaustive switch over the union so a new protocol triggers a compile error until handled."],"tags":["validation","agent-envelope","protocol","discriminated-union","typescript"],"backgroundTag":null,"analyzedSha":"5ff282f9006c436e561de1afd39a481bea1ef0d8","analyzedAt":"2026-08-12T21:38:08.145Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}