Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

📡 fix: Explain Model Streams That Die Mid-Response (#16415)

Danny Avila8ec632ff0e9e
diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.js
index a5725c12dd..a6a3991c42 100644
--- a/api/server/controllers/agents/client.test.js
+++ b/api/server/controllers/agents/client.test.js
@@ -3172,6 +3172,102 @@ describe('AgentClient - startup telemetry', () => {
errorSpy.mockRestore();
});
+ it.each([
+ [
+ 'closed',
+ 'SocketError',
+ ErrorTypes.MODEL_STREAM_CLOSED,
+ 'stream_closed',
+ 'The model provider closed the connection before the response finished. Try again.',
+ ],
+ [
+ 'stalled',
+ 'BodyTimeoutError',
+ ErrorTypes.MODEL_STREAM_STALLED,
+ 'stream_stalled',
+ 'The model provider stopped sending the response, and the request timed out. Try again.',
+ ],
+ ])(
+ 'keeps partial content and a safe %s model error in the agent turn',
+ async (kind, causeName, type, errorType, prose) => {
+ jest.clearAllMocks();
+ const { logger } = require('@librechat/data-schemas');
+ const { errors: undiciErrors } = require('undici');
+ const privateValue = 'PRIVATE-TRANSPORT-DIAGNOSTIC';
+ const cause = new undiciErrors[causeName](privateValue);
+ const providerError = new TypeError('terminated', { cause });
+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ mockCreateRun.mockImplementation(async (options) => {
+ const tracker = options.modelCallbacks.find(
+ (callback) => callback.name === 'librechat-upstream-model-error-tracker',
+ );
+ return {
+ Graph: null,
+ processStream: jest.fn(async () => {
+ tracker.handleLLMError(providerError);
+ throw new Error('graph failed', { cause: providerError });
+ }),
+ getCalibrationRatio: jest.fn(() => 0),
+ };
+ });
+ mockIsHITLEnabled.mockReturnValue(false);
+ const partial = { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial findings' };
+ const client = new AgentClient({
+ req: {
+ user: { id: 'user-123' },
+ body: {},
+ config: {
+ endpoints: { [EModelEndpoint.agents]: {} },
+ filters: { messages: { pii: {} } },
+ },
+ _resumableStreamId: `conversation-stream-${kind}`,
+ },
+ res: {},
+ agent: {
+ id: 'agent-123',
+ endpoint: EModelEndpoint.openAI,
+ provider: EModelEndpoint.openAI,
+ model_parameters: { model: 'gpt-4' },
+ hide_sequential_outputs: false,
+ },
+ endpointTokenConfig: {},
+ eventHandlers: {},
+ contentParts: [partial],
+ collectedUsage: [],
+ artifactPromises: [],
+ });
+ client.conversationId = `conversation-stream-${kind}`;
+ client.responseMessageId = `response-stream-${kind}`;
+ client.parentMessageId = `parent-stream-${kind}`;
+ client.recordCollectedUsage = jest.fn().mockResolvedValue();
+
+ try {
+ await client.chatCompletion({ payload: [] });
+
+ expect(client.contentParts).toEqual(
+ expect.arrayContaining([
+ partial,
+ {
+ type: ContentTypes.ERROR,
+ [ContentTypes.ERROR]: `${prose}\n${JSON.stringify({ type })}`,
+ },
+ ]),
+ );
+ expect(JSON.stringify(client.contentParts)).not.toContain(privateValue);
+ expect(client.recordCollectedUsage).toHaveBeenCalledWith(
+ expect.objectContaining({ context: 'message' }),
+ );
+ expect(errorSpy).toHaveBeenCalledWith(
+ '[api/server/controllers/agents/client.js #sendCompletion] Upstream model error',
+ expect.objectContaining({ errorType }),
+ );
+ expect(JSON.stringify(errorSpy.mock.calls)).not.toContain(privateValue);
+ } finally {
+ errorSpy.mockRestore();
+ }
+ },
+ );
+
/** A compaction's only record of having been one is the marker on the part it
* produced, and Compact runs on whatever leaf the branch ends with. Without
* the marker on the failure, a compaction that failed on a user leaf keeps a
diff --git a/client/src/components/Messages/Content/Error/registry.ts b/client/src/components/Messages/Content/Error/registry.ts
index 1fc44b1a95..3f878637a0 100644
--- a/client/src/components/Messages/Content/Error/registry.ts
+++ b/client/src/components/Messages/Content/Error/registry.ts
@@ -29,6 +29,8 @@ export const errorCopy: Record<string, TranslationKeys> = {
[ErrorTypes.STREAM_EXPIRED]: 'com_error_stream_expired',
[ErrorTypes.MODEL_NOT_FOUND]: 'com_error_model_not_found',
[ErrorTypes.MODEL_RATE_LIMIT]: 'com_error_model_rate_limit',
+ [ErrorTypes.MODEL_STREAM_CLOSED]: 'com_error_model_stream_closed',
+ [ErrorTypes.MODEL_STREAM_STALLED]: 'com_error_model_stream_stalled',
[ErrorTypes.COMPACTION_FAILED]: 'com_error_compaction_failed',
[ErrorTypes.AUTH_FAILED]: 'com_error_auth_failed',
[ErrorTypes.AUTH_RATE_LIMITED]: 'com_error_auth_rate_limited',
diff --git a/client/src/components/Messages/Content/__tests__/Error.spec.tsx b/client/src/components/Messages/Content/__tests__/Error.spec.tsx
index 944bbc62f8..de0c0772f4 100644
--- a/client/src/components/Messages/Content/__tests__/Error.spec.tsx
+++ b/client/src/components/Messages/Content/__tests__/Error.spec.tsx
@@ -198,6 +198,43 @@ describe('Error — reader-facing provider and fallback copy', () => {
expectReadable();
});
+ it.each([
+ [
+ ErrorTypes.MODEL_STREAM_CLOSED,
+ 'com_error_model_stream_closed',
+ 'The model provider closed the connection before the response finished. Try again.',
+ ],
+ [
+ ErrorTypes.MODEL_STREAM_STALLED,
+ 'com_error_model_stream_stalled',
+ 'The model provider stopped sending the response, and the request timed out. Try again.',
+ ],
+ ])(
+ 'localizes a %s error even when it carries older-client fallback prose',
+ (type, key, prose) => {
+ renderError(`${prose}\n${JSON.stringify({ type })}`, providerMessage);
+
+ expect(screen.getByText(catalog[key])).toBeInTheDocument();
+ expect(screen.queryByText(prose)).not.toBeInTheDocument();
+ expect(screen.queryByText(/terminated/i)).not.toBeInTheDocument();
+ expectReadable();
+ },
+ );
+
+ it('keeps fallback prose when an older client cannot recognize the server error type', () => {
+ const prose =
+ 'The model provider closed the connection before the response finished. Try again.';
+ renderError(
+ `${prose}\n${JSON.stringify({ type: 'newer_model_stream_failure' })}`,
+ providerMessage,
+ );
+
+ expect(screen.getByText(prose)).toBeInTheDocument();
+ expect(screen.queryByText(catalog.com_error_unknown)).not.toBeInTheDocument();
+ expect(document.body.textContent).not.toContain('{');
+ expectReadable();
+ });
+
it('keeps provider text for a LangChain code without localized copy, minus the URL', () => {
const raw =
'An error occurred while processing the request: could not parse output\n\nTroubleshooting URL: https://docs.langchain.com/oss/javascript/langchain/errors/OUTPUT_PARSING_FAILURE/\n';
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 2ae5ecd7f3..424f45ddde 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -571,6 +571,8 @@
"com_error_missing_model": "No model selected for {{0}}. Please select a model and try again.",
"com_error_model_not_found": "The selected model is unavailable from this provider. Select a different model or ask an administrator to verify the provider configuration.",
"com_error_model_rate_limit": "The provider declined this request for exceeding a rate or spending limit. Wait a moment and try again, or ask an administrator to review the provider's limits.",
+ "com_error_model_stream_closed": "The model provider closed the connection before the response finished. Anything already received was kept. Try again; long reasoning runs are the most likely to be cut off.",
+ "com_error_model_stream_stalled": "The model provider stopped sending the response, and the request timed out waiting for it. Anything already received was kept. Try again, or ask an administrator to check the provider.",
"com_error_models_not_loaded": "Models configuration could not be loaded. Please refresh the page and try again.",
"com_error_moderation": "This message was flagged by the moderation system, so it was not sent. Edit the message or start a new conversation.",
"com_error_no_base_url": "No base URL found. Please provide one and try again.",
diff --git a/config/create-error-convo.js b/config/create-error-convo.js
index 20e3ff3ab0..f9db4f271c 100644
--- a/config/create-error-convo.js
+++ b/config/create-error-convo.js
@@ -189,6 +189,16 @@ const ERROR_CASES = [
payloadCase('Stream expired before the client attached', { type: ErrorTypes.STREAM_EXPIRED }),
payloadCase('Model not served by this provider', { type: ErrorTypes.MODEL_NOT_FOUND }),
payloadCase('Provider rate or spend limit', { type: ErrorTypes.MODEL_RATE_LIMIT }),
+ {
+ label: 'Provider closed the stream mid-response',
+ text: `The model provider closed the connection before the response finished. Try again.\n${JSON.stringify({ type: ErrorTypes.MODEL_STREAM_CLOSED })}`,
+ covers: ErrorTypes.MODEL_STREAM_CLOSED,
+ },
+ {
+ label: 'Provider stream stalled past the response timeout',
+ text: `The model provider stopped sending the response, and the request timed out. Try again.\n${JSON.stringify({ type: ErrorTypes.MODEL_STREAM_STALLED })}`,
+ covers: ErrorTypes.MODEL_STREAM_STALLED,
+ },
{
label: 'Upstream model error with status (server prefix + JSON)',
text: `The model provider failed and the run could not recover.\n${JSON.stringify({
diff --git a/packages/api/src/agents/errors.spec.ts b/packages/api/src/agents/errors.spec.ts
index bc621f2baf..3726c154f9 100644
--- a/packages/api/src/agents/errors.spec.ts
+++ b/packages/api/src/agents/errors.spec.ts
@@ -1,5 +1,10 @@
+import { createServer } from 'node:http';
+import { Agent, errors, fetch } from 'undici';
import { ErrorTypes } from 'librechat-data-provider';
+import { ChatOpenAI } from '@librechat/agents/llm/openai';
import { GraphRecursionError } from '@langchain/langgraph';
+import type { AddressInfo } from 'node:net';
+import type { ModelErrorTrackerCallback } from './failures/tracker';
import {
GENERIC_PROVIDER_ERROR,
getLangChainErrorCode,
@@ -11,8 +16,11 @@ import {
AGENT_ATTACHMENT_LIMIT_EXCEEDED,
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,
isStepLimitError,
+ getModelStreamFailure,
+ resolveModelStreamError,
} from './errors';
import { MCPAuthenticationRejectedError, MCPAuthenticationRefreshError } from '~/mcp/errors';
+import { createTerminalRunErrorObserver } from './failures/terminal';
import { OboTokenResolutionError } from '~/mcp/oauth/obo';
import { OpenIDReauthRequiredError } from '~/utils/oidc';
@@ -306,3 +314,221 @@ describe('getAgentErrorMetadata', () => {
expect(getAgentErrorMetadata({ status })).toEqual({});
});
});
+
+type StreamEnding = 'close' | 'stall' | 'abort' | 'headers' | 'close-before-headers';
+
+interface DyingStreamClient {
+ baseURL: string;
+ fetch: typeof globalThis.fetch;
+ signal: AbortSignal;
+}
+
+/** Returns the real transport error from a provider failure before or after response headers. */
+async function readDyingStream(
+ ending: StreamEnding,
+ read: (client: DyingStreamClient) => Promise<void>,
+ firstEvent = 'data: {"delta":"Hel"}\n\n',
+): Promise<unknown> {
+ const controller = new AbortController();
+ const server = createServer((_req, res) => {
+ if (ending === 'headers') {
+ return;
+ }
+ if (ending === 'close-before-headers') {
+ setTimeout(() => res.socket?.destroy(), 20);
+ return;
+ }
+ res.writeHead(200, { 'content-type': 'text/event-stream' });
+ res.write(firstEvent);
+ if (ending === 'close') {
+ setTimeout(() => res.socket?.destroy(), 20);
+ }
+ if (ending === 'abort') {
+ setTimeout(() => controller.abort(), 20);
+ }
+ });
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+ const { port } = server.address() as AddressInfo;
+ const dispatcher = new Agent({ bodyTimeout: 150, headersTimeout: 150 });
+ const client: DyingStreamClient = {
+ baseURL: `http://127.0.0.1:${port}/v1`,
+ signal: controller.signal,
+ fetch: ((input: string, init?: object) =>
+ fetch(input, { ...init, dispatcher })) as unknown as typeof globalThis.fetch,
+ };
+ try {
+ await read(client);
+ return undefined;
+ } catch (error) {
+ return error;
+ } finally {
+ await dispatcher.destroy();
+ server.closeAllConnections();
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ }
+}
+
+const readRawBody = async ({ baseURL, fetch: read, signal }: DyingStreamClient) => {
+ const response = await read(baseURL, { signal });
+ await response.text();
+};
+
+const CHAT_COMPLETION_EVENT = `data: ${JSON.stringify({
+ id: 'chatcmpl-1',
+ object: 'chat.completion.chunk',
+ created: 0,
+ model: 'test-model',
+ choices: [{ index: 0, delta: { role: 'assistant', content: 'Hel' }, finish_reason: null }],
+})}\n\n`;
+
+const RESPONSES_EVENT = `event: response.output_text.delta\ndata: ${JSON.stringify({
+ type: 'response.output_text.delta',
+ item_id: 'msg_1',
+ output_index: 0,
+ content_index: 0,
+ delta: 'Hel',
+ sequence_number: 1,
+})}\n\n`;
+
+function streamThroughChatOpenAI(
+ useResponsesApi: boolean,
+ modelCallback?: ModelErrorTrackerCallback,
+) {
+ return async ({ baseURL, fetch: read, signal }: DyingStreamClient) => {
+ const model = new ChatOpenAI({
+ apiKey: 'test-key',
+ model: 'test-model',
+ streaming: true,
+ useResponsesApi,
+ maxRetries: 0,
+ ...(modelCallback != null ? { callbacks: [modelCallback] } : {}),
+ configuration: { baseURL, fetch: read },
+ } as never);
+ for await (const _chunk of await model.stream('hi', { signal })) {
+ /* drain */
+ }
+ };
+}
+
+describe('model stream failures', () => {
+ it('classifies a provider closing the connection mid-stream', async () => {
+ const error = await readDyingStream('close', readRawBody);
+
+ expect(error).toBeInstanceOf(TypeError);
+ expect(getModelStreamFailure(error)).toBe('closed');
+ expect(resolveModelStreamError(error)).toBe(
+ 'The model provider closed the connection before the response finished. Try again.\n' +
+ JSON.stringify({ type: ErrorTypes.MODEL_STREAM_CLOSED }),
+ );
+ });
+
+ it('classifies a provider that goes silent past the body timeout', async () => {
+ const error = await readDyingStream('stall', readRawBody);
+
+ expect(error).toBeInstanceOf(TypeError);
+ expect(getModelStreamFailure(error)).toBe('stalled');
+ expect(resolveModelStreamError(error)).toBe(
+ 'The model provider stopped sending the response, and the request timed out. Try again.\n' +
+ JSON.stringify({ type: ErrorTypes.MODEL_STREAM_STALLED }),
+ );
+ });
+
+ it('still classifies the transport failure when an outer layer rethrows it', async () => {
+ const error = await readDyingStream('stall', readRawBody);
+
+ expect(getModelStreamFailure(new Error('graph failed', { cause: error }))).toBe('stalled');
+ });
+
+ it('prefers a body timeout over a socket error found earlier in the cause chain', () => {
+ const socket = new TypeError('terminated', {
+ cause: new errors.SocketError('other side closed'),
+ });
+ const timeout = Object.assign(new errors.BodyTimeoutError(), { cause: socket });
+
+ expect(getModelStreamFailure(new Error('graph failed', { cause: timeout }))).toBe('stalled');
+ });
+
+ it('leaves a cancelled stream to the cancellation path', async () => {
+ const error = await readDyingStream('abort', readRawBody);
+
+ expect(error).toBeDefined();
+ expect(getModelStreamFailure(error)).toBeUndefined();
+ });
+
+ it.each([
+ ['Chat Completions', false, CHAT_COMPLETION_EVENT],
+ ['Responses', true, RESPONSES_EVENT],
+ ])(
+ 'tracks and classifies a real %s model stream for each ending',
+ async (_api, responses, event) => {
+ const observer = createTerminalRunErrorObserver({
+ logger: { error: jest.fn() },
+ source: '[Agent API]',
+ });
+ const read = streamThroughChatOpenAI(responses, observer.modelCallback);
+ const closed = await readDyingStream('close', read, event);
+ const stalled = await readDyingStream('stall', read, event);
+ const aborted = await readDyingStream('abort', read, event);
+
+ expect(getModelStreamFailure(closed)).toBe('closed');
+ expect(observer.getUserFacingError(closed, () => 'untracked')).toBe(
+ resolveModelStreamError(closed),
+ );
+ expect(getModelStreamFailure(stalled)).toBe('stalled');
+ expect(observer.getUserFacingError(stalled, () => 'untracked')).toBe(
+ resolveModelStreamError(stalled),
+ );
+ expect(aborted).toBeDefined();
+ expect(getModelStreamFailure(aborted)).toBeUndefined();
+ },
+ );
+
+ it.each([
+ ['waiting for headers', 'headers'],
+ ['a socket closing before headers', 'close-before-headers'],
+ ] as const)('does not mistake %s for a failed response body', async (_label, ending) => {
+ const raw = await readDyingStream(ending, readRawBody);
+ expect(raw).toBeDefined();
+ expect(getModelStreamFailure(raw)).toBeUndefined();
+
+ for (const responses of [false, true]) {
+ const modelError = await readDyingStream(ending, streamThroughChatOpenAI(responses));
+ expect(modelError).toBeDefined();
+ expect(getModelStreamFailure(modelError)).toBeUndefined();
+ }
+ });
+
+ it.each([
+ ['a provider rejection', Object.assign(new Error('500 upstream failed'), { status: 500 })],
+ ['prose that happens to say terminated', new Error('terminated')],
+ ['a bare terminated TypeError', new TypeError('terminated')],
+ ['a socket error before body streaming', new errors.SocketError('other side closed')],
+ [
+ 'a socket close wrapped by a pre-response fetch failure',
+ new TypeError('fetch failed', { cause: new errors.SocketError('other side closed') }),
+ ],
+ [
+ 'a header timeout',
+ new TypeError('fetch failed', { cause: new errors.HeadersTimeoutError() }),
+ ],
+ ['a non-error value', 'terminated'],
+ ['nothing', undefined],
+ ])('does not classify %s', (_label, error) => {
+ expect(getModelStreamFailure(error)).toBeUndefined();
+ expect(resolveModelStreamError(error)).toBeUndefined();
+ });
+
+ it('reads the cause chain without trusting hostile accessors', () => {
+ const hostile = Object.defineProperty(
+ new TypeError('terminated', { cause: new errors.BodyTimeoutError() }),
+ 'code',
+ {
+ get() {
+ throw new Error('accessor exploded');
+ },
+ },
+ );
+
+ expect(getModelStreamFailure(hostile)).toBe('stalled');
+ });
+});
diff --git a/packages/api/src/agents/errors.ts b/packages/api/src/agents/errors.ts
index 38777e7656..37f6d1b207 100644
--- a/packages/api/src/agents/errors.ts
+++ b/packages/api/src/agents/errors.ts
@@ -102,6 +102,67 @@ export function resolveLangChainError(error: unknown): string | undefined {
return type == null ? undefined : JSON.stringify({ type });
}
+export type ModelStreamFailure = 'closed' | 'stalled';
+
+/** A timeout while reading a response body, not while waiting for its headers. */
+const STALLED_TRANSPORT_CODES = new Set(['UND_ERR_BODY_TIMEOUT']);
+const STALLED_TRANSPORT_NAMES = new Set(['BodyTimeoutError']);
+/** Socket errors only describe a mid-response close when Fetch also reports body termination. */
+const CLOSED_TRANSPORT_CODES = new Set(['UND_ERR_SOCKET', 'ECONNRESET', 'EPIPE']);
+
+/**
+ * How a model response died in transit, or `undefined` for any other failure.
+ *
+ * Fetch reports both a provider hanging up mid-stream and our own body timeout as a bare
+ * `TypeError: terminated`; only the undici error in its `cause` tells them apart. A stall wins
+ * over a close found deeper in the chain, since the timeout is what ended the request.
+ */
+export function getModelStreamFailure(error: unknown): ModelStreamFailure | undefined {
+ let current = error;
+ let terminated = false;
+ let closed = false;
+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && current != null; depth++) {
+ if (typeof current !== 'object') {
+ break;
+ }
+ const code = readErrorProperty(current, 'code');
+ const name = readErrorProperty(current, 'name');
+ if (
+ (typeof code === 'string' && STALLED_TRANSPORT_CODES.has(code)) ||
+ (typeof name === 'string' && STALLED_TRANSPORT_NAMES.has(name))
+ ) {
+ return 'stalled';
+ }
+ if (typeof code === 'string' && CLOSED_TRANSPORT_CODES.has(code)) {
+ closed = true;
+ }
+ if (name === 'TypeError' && readErrorProperty(current, 'message') === 'terminated') {
+ terminated = true;
+ }
+ current = readErrorProperty(current, 'cause');
+ }
+ return closed && terminated ? 'closed' : undefined;
+}
+
+const MODEL_STREAM_ERROR_TYPES: Record<ModelStreamFailure, ErrorTypes> = {
+ closed: ErrorTypes.MODEL_STREAM_CLOSED,
+ stalled: ErrorTypes.MODEL_STREAM_STALLED,
+};
+
+/** Safe fallback for an older client that cannot localize these new error types yet. */
+const MODEL_STREAM_FALLBACK: Record<ModelStreamFailure, string> = {
+ closed: 'The model provider closed the connection before the response finished. Try again.',
+ stalled: 'The model provider stopped sending the response, and the request timed out. Try again.',
+};
+
+/** Typed payload for new clients, with useful prose when the client bundle predates these types. */
+export function resolveModelStreamError(error: unknown): string | undefined {
+ const failure = getModelStreamFailure(error);
+ return failure == null
+ ? undefined
+ : `${MODEL_STREAM_FALLBACK[failure]}\n${JSON.stringify({ type: MODEL_STREAM_ERROR_TYPES[failure] })}`;
+}
+
/**
* Provider failure text for OpenAI-compatible responses, which carry raw strings rather than the
* typed payloads the LibreChat client localizes.
diff --git a/packages/api/src/agents/failures/terminal.spec.ts b/packages/api/src/agents/failures/terminal.spec.ts
index 18421f9a3f..d0e1308afc 100644
--- a/packages/api/src/agents/failures/terminal.spec.ts
+++ b/packages/api/src/agents/failures/terminal.spec.ts
@@ -1,3 +1,4 @@
+import { errors } from 'undici';
import { createTerminalRunErrorObserver, getUpstreamModelErrorMetadata } from './terminal';
describe('terminal agent-run error logging', () => {
@@ -217,13 +218,111 @@ describe('terminal agent-run error logging', () => {
);
});
+ it.each([
+ [
+ 'stalled',
+ new errors.BodyTimeoutError(),
+ 'model_stream_stalled',
+ 'The model provider stopped sending the response, and the request timed out. Try again.',
+ ],
+ [
+ 'closed',
+ new errors.SocketError('other side closed'),
+ 'model_stream_closed',
+ 'The model provider closed the connection before the response finished. Try again.',
+ ],
+ ])(
+ 'names a %s model stream instead of the bare transport error',
+ (failure, cause, type, prose) => {
+ const logger = { error: jest.fn() };
+ const observer = createTerminalRunErrorObserver({
+ logger,
+ source: '[Agent API]',
+ protectionEnabled: false,
+ });
+ const transportError = new TypeError('terminated', { cause });
+ observer.modelCallback.handleLLMError(transportError);
+ const terminalError = new Error('graph failed', { cause: transportError });
+
+ expect(observer.getUserFacingError(terminalError, () => 'fallback')).toBe(
+ `${prose}\n${JSON.stringify({ type })}`,
+ );
+ observer.log(terminalError);
+ expect(logger.error).toHaveBeenCalledWith(
+ '[Agent API] Upstream model error',
+ expect.objectContaining({ errorType: `stream_${failure}` }),
+ );
+ },
+ );
+
+ it.each([
+ ['a response header timeout', new errors.HeadersTimeoutError()],
+ ['a pre-response socket close', new errors.SocketError('other side closed')],
+ ])('keeps %s on the generic upstream path', (_label, cause) => {
+ const logger = { error: jest.fn() };
+ const observer = createTerminalRunErrorObserver({
+ logger,
+ source: '[Agent API]',
+ protectionEnabled: true,
+ });
+ const transportError = new TypeError('fetch failed', { cause });
+ observer.modelCallback.handleLLMError(transportError);
+
+ expect(observer.getUserFacingError(transportError, () => 'fallback')).toBe(
+ 'The model provider could not complete this request.\n' +
+ JSON.stringify({ type: 'upstream_model_error' }),
+ );
+ observer.log(transportError);
+ expect(logger.error).toHaveBeenCalledWith(
+ '[Agent API] Upstream model error',
+ expect.objectContaining({ errorType: '_OTHER' }),
+ );
+ });
+
+ it.each([
+ [200, 'stream_stalled', 'model_stream_stalled'],
+ [502, '502', 'upstream_model_error'],
+ ])('keeps HTTP %i and a body timeout in their correct categories', (status, errorType, type) => {
+ const logger = { error: jest.fn() };
+ const observer = createTerminalRunErrorObserver({
+ logger,
+ source: '[Agent API]',
+ protectionEnabled: true,
+ });
+ const failure = Object.assign(
+ new TypeError('terminated', { cause: new errors.BodyTimeoutError() }),
+ { response: { status } },
+ );
+ observer.modelCallback.handleLLMError(failure);
+
+ const userError = observer.getUserFacingError(failure, () => 'fallback');
+ expect(userError).toContain(JSON.stringify({ type, ...(status >= 400 ? { status } : {}) }));
+ expect(userError).not.toContain('terminated');
+ observer.log(failure);
+ expect(logger.error).toHaveBeenCalledWith(
+ '[Agent API] Upstream model error',
+ expect.objectContaining({ errorType, status }),
+ );
+ });
+
+ it('keeps an untracked transport failure off the upstream model path', () => {
+ const observer = createTerminalRunErrorObserver({
+ logger: { error: jest.fn() },
+ source: '[Agent API]',
+ protectionEnabled: false,
+ });
+ const transportError = new TypeError('terminated', { cause: new errors.BodyTimeoutError() });
+
+ expect(observer.getUserFacingError(transportError, () => 'fallback')).toBe('fallback');
+ });
+
it('preserves a more specific localized model classification', () => {
const observer = createTerminalRunErrorObserver({
logger: { error: jest.fn() },
source: '[Agent API]',
protectionEnabled: false,
});
- const providerError = new Error('provider failed');
+ const providerError = new TypeError('terminated', { cause: new errors.BodyTimeoutError() });
const terminalError = Object.assign(new Error('rate limited', { cause: providerError }), {
lc_error_code: 'MODEL_RATE_LIMIT',
});
diff --git a/packages/api/src/agents/failures/terminal.ts b/packages/api/src/agents/failures/terminal.ts
index ce2fcf5909..79e054ad8d 100644
--- a/packages/api/src/agents/failures/terminal.ts
+++ b/packages/api/src/agents/failures/terminal.ts
@@ -1,8 +1,13 @@
import { ErrorTypes } from 'librechat-data-provider';
import type { SafeErrorMetadata } from '../../utils/errors';
import type { ModelErrorTrackerCallback } from './tracker';
+import {
+ resolveLangChainError,
+ getModelStreamFailure,
+ resolveModelStreamError,
+ getProviderErrorMessage,
+} from '../errors';
import { getSafeErrorMetadata, isOwnedAbortError } from '../../utils/errors';
-import { getProviderErrorMessage, resolveLangChainError } from '../errors';
import { traceIdForMessage } from '../../langfuse/trace';
import { createModelErrorTracker } from './tracker';
@@ -41,6 +46,18 @@ export function isAgentRunCancellation(error: unknown, signal?: AbortSignal): bo
return isOwnedAbortError(error, signal);
}
+/** Preserve rejection status; a successful status can still precede a broken response body. */
+function getUpstreamErrorType(error: unknown, status?: number): string {
+ if (status != null && status >= 400) {
+ return String(status);
+ }
+ const streamFailure = getModelStreamFailure(error);
+ if (streamFailure != null) {
+ return `stream_${streamFailure}`;
+ }
+ return status == null ? UNKNOWN_UPSTREAM_MODEL_ERROR_TYPE : String(status);
+}
+
export function getUpstreamModelErrorMetadata(
error: unknown,
responseMessageId?: string,
@@ -50,8 +67,7 @@ export function getUpstreamModelErrorMetadata(
...safeMetadata,
errorCode: UPSTREAM_MODEL_ERROR_CODE,
errorOrigin: UPSTREAM_MODEL_ERROR_ORIGIN,
- errorType:
- safeMetadata.status != null ? String(safeMetadata.status) : UNKNOWN_UPSTREAM_MODEL_ERROR_TYPE,
+ errorType: getUpstreamErrorType(error, safeMetadata.status),
...(typeof responseMessageId === 'string' && responseMessageId !== ''
? { traceId: traceIdForMessage(responseMessageId) }
: {}),
@@ -89,13 +105,17 @@ export function createTerminalRunErrorObserver({
return fallback();
}
+ const { status } = getSafeErrorMetadata(upstreamModelError);
const classifiedError =
- safelyResolveLangChainError(error) ?? safelyResolveLangChainError(upstreamModelError);
+ safelyResolveLangChainError(error) ??
+ safelyResolveLangChainError(upstreamModelError) ??
+ (status == null || status < 400
+ ? (resolveModelStreamError(upstreamModelError) ?? resolveModelStreamError(error))
+ : undefined);
if (classifiedError != null) {
return classifiedError;
}
- const { status } = getSafeErrorMetadata(upstreamModelError);
/** Unclassified: the provider's own explanation is the only account of what happened, and a
* rejection from a gateway or proxy carries it as the whole point of the 400. The status
* headlines it either way, so a deployment withholding provider text loses no taxonomy. */
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 7afb9cb280..dfb835647e 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -3913,6 +3913,14 @@ export enum ErrorTypes {
* Provider throttled or refused the request for exceeding a rate/spend allowance
*/
MODEL_RATE_LIMIT = 'model_rate_limit',
+ /**
+ * Provider accepted the request, then closed the connection before the response finished
+ */
+ MODEL_STREAM_CLOSED = 'model_stream_closed',
+ /**
+ * Provider accepted the request, then sent nothing for longer than the model response timeout
+ */
+ MODEL_STREAM_STALLED = 'model_stream_stalled',
/**
* An agent model provider failed and the run could not recover.
*/