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: Encode Images From Storage Keys (#15851)

Haobd08a363c434
diff --git a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
index dae2a4861a..742917090c 100644
--- a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
+++ b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js
@@ -65,6 +65,8 @@ jest.mock('@librechat/api', () => ({
resolveTitleTiming: jest.fn(() => 'immediate'),
resolveConversationAnchor: jest.requireActual('@librechat/api').resolveConversationAnchor,
resolveRunCodeWorkspaces: jest.requireActual('@librechat/api').resolveRunCodeWorkspaces,
+ getSafeErrorMetadata: jest.requireActual('@librechat/api').getSafeErrorMetadata,
+ getSafeErrorText: jest.requireActual('@librechat/api').getSafeErrorText,
GenerationJobManager: mockGenerationJobManager,
getReferencedQuotes: jest.fn(() => null),
cleanupMCPRequestContext: jest.fn(),
diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
index b81a06fffa..3d8d74b261 100644
--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js
@@ -274,8 +274,12 @@ jest.mock('@librechat/api', () => ({
resolveTitleTiming: jest.fn(() => 'immediate'),
resolveConversationAnchor: jest.requireActual('@librechat/api').resolveConversationAnchor,
resolveRunCodeWorkspaces: jest.requireActual('@librechat/api').resolveRunCodeWorkspaces,
+ AttachmentStorageError: jest.requireActual('@librechat/api').AttachmentStorageError,
+ encodeAndFormatImages: jest.requireActual('@librechat/api').encodeAndFormatImages,
getCodeWorkspaceSelectionErrorDetails:
jest.requireActual('@librechat/api').getCodeWorkspaceSelectionErrorDetails,
+ getSafeErrorMetadata: jest.requireActual('@librechat/api').getSafeErrorMetadata,
+ getSafeErrorText: jest.requireActual('@librechat/api').getSafeErrorText,
GenerationJobManager: mockGenerationJobManager,
getReferencedQuotes: jest.fn((quotes) => {
if (!Array.isArray(quotes)) {
@@ -400,6 +404,7 @@ jest.mock('~/server/services/Agents/triggers', () => ({
}));
const AgentController = require('../request');
+const { AttachmentStorageError, encodeAndFormatImages } = require('@librechat/api');
const { ErrorTypes } = require('librechat-data-provider');
const { disposeClient: mockDisposeClient } = require('~/server/cleanup');
const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');
@@ -2602,6 +2607,134 @@ describe('ResumableAgentController resume metadata', () => {
expect(mockDecrementPendingRequest).toHaveBeenCalledWith('user-123');
});
+ it('names the failure class at the initialization boundary', async () => {
+ const initializeClient = jest.fn().mockRejectedValue(new AttachmentStorageError());
+ const req = {
+ user: { id: 'user-123' },
+ body: {
+ text: 'Describe the attached image.',
+ messageId: 'user-msg',
+ clientRequestId: 'req-abc',
+ conversationId: 'conversation-123',
+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },
+ },
+ config: {},
+ };
+ const res = createResumableResponse();
+
+ await AgentController(req, res, jest.fn(), initializeClient, null);
+
+ const [message, ...metadata] = mockLogger.error.mock.calls.find((call) =>
+ String(call[0]).startsWith('[ResumableAgentController] Initialization error:'),
+ );
+ expect(metadata).toEqual([]);
+ expect(message).toContain(
+ 'AttachmentStorageError: An attached file could not be read from storage.',
+ );
+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(
+ 'conversation-123',
+ 'An attached file could not be read from storage. Try again or upload it again.',
+ 1000,
+ expect.objectContaining({ beforeErrorPublication: expect.any(Function) }),
+ );
+ });
+
+ it('redacts a signed storage URL an initialization failure carries into the log', async () => {
+ const signedUrl =
+ 'https://minio.example.com/bucket/image.png?X-Amz-Credential=secret&X-Amz-Signature=signed';
+ const initializeClient = jest
+ .fn()
+ .mockRejectedValue(new Error(`AccessDenied reading ${signedUrl}`));
+ const req = {
+ user: { id: 'user-123' },
+ body: {
+ text: 'Describe the attached image.',
+ messageId: 'user-msg',
+ clientRequestId: 'req-abc',
+ conversationId: 'conversation-123',
+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },
+ },
+ config: {},
+ };
+
+ await AgentController(req, createResumableResponse(), jest.fn(), initializeClient, null);
+
+ const [message, ...metadata] = mockLogger.error.mock.calls.find((call) =>
+ String(call[0]).startsWith('[ResumableAgentController] Initialization error:'),
+ );
+ expect(metadata).toEqual([]);
+ expect(message).toContain('AccessDenied reading https://minio.example.com/[redacted]');
+ expect(message).not.toContain('X-Amz-Signature');
+ expect(JSON.stringify(mockLogger.error.mock.calls)).not.toContain(signedUrl);
+ });
+
+ it('publishes a safe image storage failure during generation and releases the request', async () => {
+ const signedUrl =
+ 'https://minio.example.com/bucket/image.png?X-Amz-Credential=secret&X-Amz-Signature=signed';
+ const storageError = Object.assign(new Error(`Access denied for ${signedUrl}`), {
+ code: 'AccessDenied',
+ statusCode: 403,
+ });
+ const getDownloadStream = jest.fn().mockRejectedValue(storageError);
+ const file = {
+ file_id: 'image-1',
+ source: 's3',
+ filepath: signedUrl,
+ storageKey: 'images/user/image.png',
+ height: 10,
+ width: 10,
+ };
+ const req = {
+ user: { id: 'user-123' },
+ body: {
+ text: 'Describe the attached image.',
+ messageId: 'user-msg',
+ conversationId: 'conversation-123',
+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },
+ },
+ config: {},
+ };
+ const client = {
+ options: {},
+ sendMessage: jest.fn(() =>
+ encodeAndFormatImages(
+ req,
+ [file],
+ {},
+ { getStrategyFunctions: () => ({ getDownloadStream }) },
+ ),
+ ),
+ };
+ const initializeClient = jest.fn().mockResolvedValue({ client });
+
+ await AgentController(req, createResumableResponse(), jest.fn(), initializeClient, null);
+ await nextTick();
+
+ const safeError = new AttachmentStorageError();
+ expect(getDownloadStream).toHaveBeenCalledWith(req, file.storageKey);
+ expect(mockLogger.error).toHaveBeenCalledWith(
+ '[ResumableAgentController] Generation error for conversation-123:',
+ safeError,
+ );
+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(
+ 'conversation-123',
+ safeError.message,
+ 1000,
+ expect.objectContaining({ beforeErrorPublication: expect.any(Function) }),
+ );
+ expect(mockSaveMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ userId: 'user-123' }),
+ expect.objectContaining({ error: true, text: safeError.message }),
+ expect.any(Object),
+ );
+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith('user-123');
+ expect(mockDisposeClient).toHaveBeenCalledWith(client);
+ expect(JSON.stringify(mockGenerationJobManager.completeJob.mock.calls)).not.toContain(
+ signedUrl,
+ );
+ expect(JSON.stringify(mockSaveMessage.mock.calls)).not.toContain(signedUrl);
+ });
+
it('returns a typed recovery conflict before acknowledging generation startup', async () => {
const recoveryError = new Error('Attached resources could not be restored');
recoveryError.code = ErrorTypes.RESOURCE_RECOVERY_REQUIRED;
diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.js
index 20578cffd9..b2e3904d20 100644
--- a/api/server/controllers/agents/request.js
+++ b/api/server/controllers/agents/request.js
@@ -30,6 +30,7 @@ const {
getAttachmentTitleText,
createMCPRuntimeRequestBody,
resolveRunCodeWorkspaces,
+ getSafeErrorText,
isAgentEventRetentionActive,
createAgentEventActorTurn,
createAgentEventActorDetachedActionLifecycle,
@@ -3288,7 +3289,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
);
});
} catch (error) {
- logger.error('[ResumableAgentController] Initialization error:', error);
+ logger.error(`[ResumableAgentController] Initialization error: ${getSafeErrorText(error)}`);
const initializationFailure = getInitializationFailure(error);
const streamStarted = res.headersSent;
try {
diff --git a/api/server/controllers/assistants/chat.contentFilter.spec.js b/api/server/controllers/assistants/chat.contentFilter.spec.js
index 52d569a6e8..9b3e630102 100644
--- a/api/server/controllers/assistants/chat.contentFilter.spec.js
+++ b/api/server/controllers/assistants/chat.contentFilter.spec.js
@@ -11,6 +11,7 @@ const mockRetrieveAssistant = jest.fn();
const mockListThreadMessages = jest.fn();
const mockGetConvo = jest.fn();
const mockGetFiles = jest.fn();
+const mockEncodeAndFormat = jest.fn();
const mockGetOpenAIClient = jest.fn().mockResolvedValue({
openai: {
beta: {
@@ -90,7 +91,7 @@ jest.mock('~/app/clients/prompts', () => ({
}));
jest.mock('~/server/services/Files/images/encode', () => ({
- encodeAndFormat: jest.fn(),
+ encodeAndFormat: (...args) => mockEncodeAndFormat(...args),
}));
jest.mock('~/server/services/Runs', () => ({
@@ -135,6 +136,8 @@ jest.mock('./helpers', () => ({
const chatV1 = require('./chatV1');
const chatV2 = require('./chatV2');
+const { logger } = require('@librechat/data-schemas');
+const { ImageVisionTool } = require('librechat-data-provider');
describe.each([
['v1', chatV1],
@@ -157,6 +160,7 @@ describe.each([
});
mockGetFiles.mockReset().mockResolvedValue([]);
mockGetConvo.mockReset().mockResolvedValue(null);
+ mockEncodeAndFormat.mockReset().mockResolvedValue({ files: [], image_urls: [] });
mockInitThread.mockReset();
closeHandler = undefined;
req = {
@@ -382,6 +386,41 @@ describe.each([
});
if (_version === 'v1') {
+ describe('V1 vision attachment failures', () => {
+ it('does not log a signed storage URL from an image encoding error', async () => {
+ const signedUrl =
+ 'https://minio.example.com/bucket/image.png?X-Amz-Credential=secret&X-Amz-Signature=signed';
+ const failure = Object.assign(new Error(`NoSuchKey for ${signedUrl}`), {
+ statusCode: 404,
+ });
+ mockRetrieveAssistant.mockResolvedValueOnce({
+ id: 'asst-1',
+ instructions: 'Safe assistant',
+ tools: [{ type: 'function', function: { name: ImageVisionTool.function.name } }],
+ });
+ req.body.endpointOption.attachments = Promise.resolve([
+ {
+ source: 's3',
+ filepath: signedUrl,
+ storageKey: 'images/user/image.png',
+ },
+ ]);
+ mockEncodeAndFormat.mockRejectedValueOnce(failure);
+
+ await chatV1(req, res);
+
+ expect(mockEncodeAndFormat).toHaveBeenCalled();
+ const [message, ...metadata] = logger.error.mock.calls.find((call) =>
+ String(call[0]).startsWith('[/assistants/chat/]'),
+ );
+ expect(metadata).toEqual([]);
+ expect(message).toContain('NoSuchKey for https://minio.example.com/[redacted]');
+ expect(message).not.toContain('X-Amz-Signature');
+ expect(JSON.stringify(logger.error.mock.calls)).not.toContain(signedUrl);
+ expect(JSON.stringify(mockSendResponse.mock.calls)).not.toContain(signedUrl);
+ });
+ });
+
describe('V1 final conversation-file preflight', () => {
beforeEach(() => {
req.config.filters = {
diff --git a/api/server/controllers/assistants/chatV1.js b/api/server/controllers/assistants/chatV1.js
index 5b33daa795..5db12b8700 100644
--- a/api/server/controllers/assistants/chatV1.js
+++ b/api/server/controllers/assistants/chatV1.js
@@ -6,6 +6,7 @@ const {
countTokens,
checkBalance,
getBalanceConfig,
+ getSafeErrorText,
getModelMaxTokens,
getTransactionsConfig,
ATTACHMENT_ONLY_TEXT,
@@ -164,7 +165,7 @@ const chatV1 = async (req, res) => {
} else if (error?.message?.includes(ViolationTypes.TOKEN_BALANCE)) {
return sendResponse(req, res, messageData, error.message);
} else {
- logger.error('[/assistants/chat/]', error);
+ logger.error(`[/assistants/chat/] ${getSafeErrorText(error)}`);
}
if (!openai || !thread_id || !run_id) {
diff --git a/api/server/services/Files/Azure/crud.js b/api/server/services/Files/Azure/crud.js
index 5944f40ab7..1fea4db7d5 100644
--- a/api/server/services/Files/Azure/crud.js
+++ b/api/server/services/Files/Azure/crud.js
@@ -6,6 +6,7 @@ const { logger } = require('@librechat/data-schemas');
const {
deleteRagFile,
assertRemoteFileURL,
+ getSafeErrorMetadata,
getAzureContainerClient,
getRemoteFileFetchMaxBytes,
getRemoteFileFetchTimeoutMs,
@@ -287,7 +288,7 @@ async function getAzureFileStream(_req, fileURL, { signal } = {}) {
}
return response.readableStreamBody;
} catch (error) {
- logger.error('[getAzureFileStream] Error getting blob stream:', error);
+ logger.error('[getAzureFileStream] Error getting blob stream:', getSafeErrorMetadata(error));
throw error;
}
}
diff --git a/api/server/services/Files/Azure/crud.spec.js b/api/server/services/Files/Azure/crud.spec.js
index c7e87b1d9b..bafbb98430 100644
--- a/api/server/services/Files/Azure/crud.spec.js
+++ b/api/server/services/Files/Azure/crud.spec.js
@@ -4,6 +4,7 @@ const mockGetAzureContainerClient = jest.fn(async () => ({
url: 'https://account.blob.core.windows.net/files',
getBlockBlobClient: mockGetBlockBlobClient,
}));
+const mockGetSafeErrorMetadata = jest.fn(() => ({ type: 'Error', status: 403 }));
jest.mock('@librechat/data-schemas', () => ({
logger: { error: jest.fn() },
@@ -12,12 +13,14 @@ jest.mock('@librechat/data-schemas', () => ({
jest.mock('@librechat/api', () => ({
deleteRagFile: jest.fn(),
assertRemoteFileURL: jest.fn((url) => url),
+ getSafeErrorMetadata: (...args) => mockGetSafeErrorMetadata(...args),
getAzureContainerClient: (...args) => mockGetAzureContainerClient(...args),
getRemoteFileFetchMaxBytes: jest.fn(() => 1024),
getRemoteFileFetchTimeoutMs: jest.fn(() => 1000),
assertRemoteFileContentLength: jest.fn(),
}));
+const { logger } = require('@librechat/data-schemas');
const { getAzureFileStream } = require('./crud');
describe('getAzureFileStream', () => {
@@ -54,4 +57,22 @@ describe('getAzureFileStream', () => {
expect(mockGetAzureContainerClient).toHaveBeenCalledWith();
expect(mockGetBlockBlobClient).toHaveBeenCalledWith('uploads/user/report one.pdf');
});
+
+ it('logs bounded metadata without the signed blob URL', async () => {
+ const signedUrl =
+ 'https://account.blob.core.windows.net/files/uploads/user/report.pdf?sig=secret';
+ const failure = Object.assign(new Error(`Request failed for ${signedUrl}`), {
+ statusCode: 403,
+ });
+ mockDownload.mockRejectedValue(failure);
+
+ await expect(getAzureFileStream({}, signedUrl)).rejects.toBe(failure);
+
+ expect(mockGetSafeErrorMetadata).toHaveBeenCalledWith(failure);
+ expect(logger.error).toHaveBeenCalledWith('[getAzureFileStream] Error getting blob stream:', {
+ type: 'Error',
+ status: 403,
+ });
+ expect(JSON.stringify(logger.error.mock.calls)).not.toContain(signedUrl);
+ });
});
diff --git a/api/server/services/Files/Firebase/crud.js b/api/server/services/Files/Firebase/crud.js
index cf6d4c74e3..174b473751 100644
--- a/api/server/services/Files/Firebase/crud.js
+++ b/api/server/services/Files/Firebase/crud.js
@@ -7,6 +7,7 @@ const {
deleteRagFile,
getFirebaseStorage,
assertRemoteFileURL,
+ getSafeErrorMetadata,
getRemoteFileFetchMaxBytes,
getRemoteFileFetchTimeoutMs,
assertRemoteFileContentLength,
@@ -265,7 +266,7 @@ async function getFirebaseFileStream(_req, filepath, { signal } = {}) {
return response.data;
} catch (error) {
- logger.error('Error getting Firebase file stream:', error);
+ logger.error('Error getting Firebase file stream:', getSafeErrorMetadata(error));
throw error;
}
}
diff --git a/api/server/services/Files/images/encode.js b/api/server/services/Files/images/encode.js
index dc744542f1..8119c544c3 100644
--- a/api/server/services/Files/images/encode.js
+++ b/api/server/services/Files/images/encode.js
@@ -1,268 +1,10 @@
const axios = require('axios');
-const { logger } = require('@librechat/data-schemas');
-const { logAxiosError, validateImage, runGuardedEncode } = require('@librechat/api');
-const {
- FileSources,
- VisionModes,
- ImageDetail,
- ContentTypes,
- EModelEndpoint,
- mergeFileConfig,
- getEndpointFileConfig,
-} = require('librechat-data-provider');
+const { encodeAndFormatImages } = require('@librechat/api');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
-/**
- * Converts a readable stream to a base64 encoded string.
- *
- * @param {NodeJS.ReadableStream} stream - The readable stream to convert.
- * @param {boolean} [destroyStream=true] - Whether to destroy the stream after processing.
- * @returns {Promise<string>} - Promise resolving to the base64 encoded content.
- */
-async function streamToBase64(stream, destroyStream = true) {
- return new Promise((resolve, reject) => {
- const chunks = [];
-
- stream.on('data', (chunk) => {
- chunks.push(chunk);
- });
-
- stream.on('end', () => {
- try {
- const buffer = Buffer.concat(chunks);
- const base64Data = buffer.toString('base64');
- chunks.length = 0; // Clear the array
- resolve(base64Data);
- } catch (err) {
- reject(err);
- }
- });
-
- stream.on('error', (error) => {
- chunks.length = 0;
- reject(error);
- });
- }).finally(() => {
- // Clean up the stream if required
- if (destroyStream && stream.destroy && typeof stream.destroy === 'function') {
- stream.destroy();
- }
- });
-}
-
-/**
- * Fetches an image from a URL and returns its base64 representation.
- *
- * @async
- * @param {string} url The URL of the image.
- * @returns {Promise<string>} The base64-encoded string of the image.
- * @throws {Error} If there's an issue fetching the image or encoding it.
- */
-async function fetchImageToBase64(url) {
- try {
- const response = await axios.get(url, {
- responseType: 'arraybuffer',
- });
- const base64Data = Buffer.from(response.data).toString('base64');
- response.data = null;
- return base64Data;
- } catch (error) {
- const message = 'Error fetching image to convert to base64';
- throw new Error(logAxiosError({ message, error }));
- }
-}
-
-const base64Only = new Set([
- EModelEndpoint.google,
- EModelEndpoint.anthropic,
- 'Ollama',
- 'ollama',
- EModelEndpoint.bedrock,
-]);
-
-const blobStorageSources = new Set([
- FileSources.azure_blob,
- FileSources.s3,
- FileSources.firebase,
- FileSources.cloudfront,
-]);
-
-/**
- * Encodes and formats the given files.
- * @param {ServerRequest} req - The request object.
- * @param {Array<MongoFile>} files - The array of files to encode and format.
- * @param {object} params - Object containing provider/endpoint information
- * @param {Providers | EModelEndpoint | string} [params.provider] - The provider for the image
- * @param {string} [params.endpoint] - Optional: The endpoint for the image
- * @param {string} [params.imageDetail] - Optional: Detail level resolved by the caller, used
- * where the request body carries no conversation-level setting (the agents route).
- * @param {string} [mode] - Optional: The endpoint mode for the image.
- * @returns {Promise<{ files: MongoFile[]; image_urls: MessageContentImageUrl[] }>} - A promise that resolves to the result object containing the encoded images and file details.
- */
-async function encodeAndFormat(req, files, params, mode) {
- const { provider, endpoint } = params;
- const effectiveEndpoint = endpoint ?? provider;
- const promises = [];
- /** @type {Record<FileSources, Pick<ReturnType<typeof getStrategyFunctions>, 'prepareImagePayload' | 'getDownloadStream'>>} */
- const encodingMethods = {};
- /** @type {{ files: MongoFile[]; image_urls: MessageContentImageUrl[] }} */
- const result = {
- files: [],
- image_urls: [],
- };
-
- if (!files || !files.length) {
- return result;
- }
-
- for (let file of files) {
- /** @type {FileSources} */
- const source = file.source ?? FileSources.local;
-
- if (!file.height) {
- promises.push([file, null]);
- continue;
- }
-
- if (!encodingMethods[source]) {
- const { prepareImagePayload, getDownloadStream } = getStrategyFunctions(source);
- if (!prepareImagePayload) {
- throw new Error(`Encoding function not implemented for ${source}`);
- }
-
- encodingMethods[source] = { prepareImagePayload, getDownloadStream };
- }
-
- const preparePayload = encodingMethods[source].prepareImagePayload;
- /* We need to fetch the image and convert it to base64 if we are using S3/Azure Blob/Firebase storage. */
- if (blobStorageSources.has(source)) {
- try {
- const downloadStream = encodingMethods[source].getDownloadStream;
- let base64Data = await runGuardedEncode(file.bytes ?? 0, async () => {
- let stream = await downloadStream(req, file.filepath);
- const data = await streamToBase64(stream);
- stream = null;
- return data;
- });
- promises.push([file, base64Data]);
- base64Data = null;
- continue;
- } catch (error) {
- logger.error('Error processing image from blob storage:', error);
- }
- } else if (source !== FileSources.local && base64Only.has(effectiveEndpoint)) {
- const entry = await runGuardedEncode(file.bytes ?? 0, async () => {
- const [_file, imageURL] = await preparePayload(req, file);
- return [_file, await fetchImageToBase64(imageURL)];
- });
- promises.push(entry);
- continue;
- }
- promises.push(preparePayload(req, file));
- }
-
- const detail = params.imageDetail ?? req.body.imageDetail ?? ImageDetail.auto;
-
- /** @type {Array<[MongoFile, string]>} */
- const formattedImages = await Promise.all(promises);
- promises.length = 0;
-
- /** Extract configured file size limit from fileConfig for this endpoint */
- let configuredFileSizeLimit;
- if (req.config?.fileConfig) {
- const fileConfig = mergeFileConfig(req.config.fileConfig);
- const endpointConfig = getEndpointFileConfig({
- fileConfig,
- endpoint: effectiveEndpoint,
- });
- configuredFileSizeLimit = endpointConfig?.fileSizeLimit;
- }
-
- for (const [file, imageContent] of formattedImages) {
- const fileMetadata = {
- type: file.type,
- file_id: file.file_id,
- filepath: file.filepath,
- filename: file.filename,
- embedded: !!file.embedded,
- metadata: file.metadata,
- };
-
- if (file.height && file.width) {
- fileMetadata.height = file.height;
- fileMetadata.width = file.width;
- }
-
- if (!imageContent) {
- result.files.push(fileMetadata);
- continue;
- }
-
- /** Validate image buffer against size limits */
- if (file.height && file.width) {
- const imageBuffer = imageContent.startsWith('http')
- ? null
- : Buffer.from(imageContent, 'base64');
-
- if (imageBuffer) {
- const validation = await validateImage(
- imageBuffer,
- imageBuffer.length,
- effectiveEndpoint,
- configuredFileSizeLimit,
- );
-
- if (!validation.isValid) {
- throw new Error(`Image validation failed for ${file.filename}: ${validation.error}`);
- }
- }
- }
-
- const imagePart = {
- type: ContentTypes.IMAGE_URL,
- image_url: {
- url: imageContent.startsWith('http')
- ? imageContent
- : `data:${file.type};base64,${imageContent}`,
- detail,
- },
- };
-
- if (mode === VisionModes.agents) {
- result.image_urls.push({ ...imagePart });
- result.files.push({ ...fileMetadata });
- continue;
- }
-
- if (
- effectiveEndpoint &&
- effectiveEndpoint === EModelEndpoint.google &&
- mode === VisionModes.generative
- ) {
- delete imagePart.image_url;
- imagePart.inlineData = {
- mimeType: file.type,
- data: imageContent,
- };
- } else if (effectiveEndpoint && effectiveEndpoint === EModelEndpoint.google) {
- imagePart.image_url = imagePart.image_url.url;
- } else if (effectiveEndpoint && effectiveEndpoint === EModelEndpoint.anthropic) {
- imagePart.type = 'image';
- imagePart.source = {
- type: 'base64',
- media_type: file.type,
- data: imageContent,
- };
- delete imagePart.image_url;
- }
-
- result.image_urls.push({ ...imagePart });
- result.files.push({ ...fileMetadata });
- }
- formattedImages.length = 0;
- return { ...result };
-}
+const dependencies = { getStrategyFunctions, httpClient: axios };
module.exports = {
- encodeAndFormat,
+ encodeAndFormat: (req, files, params, mode) =>
+ encodeAndFormatImages(req, files, params, dependencies, mode),
};
diff --git a/api/server/services/Files/images/encode.spec.js b/api/server/services/Files/images/encode.spec.js
index 262a55be45..525a38421f 100644
--- a/api/server/services/Files/images/encode.spec.js
+++ b/api/server/services/Files/images/encode.spec.js
@@ -1,164 +1,60 @@
-const { Readable } = require('stream');
-
-const mockRunGuardedEncode = jest.fn((_bytes, task) => task());
-
-jest.mock('axios');
-jest.mock('@librechat/api', () => ({
- logAxiosError: jest.fn(({ message }) => message),
- validateImage: jest.fn().mockResolvedValue({ isValid: true }),
- runGuardedEncode: (...args) => mockRunGuardedEncode(...args),
-}));
-jest.mock('@librechat/data-schemas', () => ({
- logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
-}));
-
-const mockPrepareImagePayload = jest.fn();
-const mockGetDownloadStream = jest.fn();
-jest.mock('~/server/services/Files/strategies', () => ({
- getStrategyFunctions: jest.fn(() => ({
- prepareImagePayload: mockPrepareImagePayload,
- getDownloadStream: mockGetDownloadStream,
- })),
-}));
+jest.mock('@librechat/api', () => ({ encodeAndFormatImages: jest.fn() }));
+jest.mock('~/server/services/Files/strategies', () => ({ getStrategyFunctions: jest.fn() }));
const axios = require('axios');
-const { FileSources } = require('librechat-data-provider');
+const { Readable } = require('node:stream');
+const { encodeAndFormatImages } = require('@librechat/api');
+const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { encodeAndFormat } = require('./encode');
-const makeReq = () => ({ body: {}, config: {} });
-
-beforeEach(() => {
- jest.clearAllMocks();
- mockRunGuardedEncode.mockImplementation((_bytes, task) => task());
+beforeEach(() => jest.resetAllMocks());
+
+it('wires the existing callers to the typed image encoder without interpreting its result', () => {
+ const req = { body: {}, config: {} };
+ const files = [];
+ const params = { endpoint: 'openai', imageDetail: 'high' };
+ const result = Promise.resolve({ files: [], image_urls: [] });
+ encodeAndFormatImages.mockReturnValue(result);
+
+ expect(encodeAndFormat(req, files, params, 'agents')).toBe(result);
+ expect(encodeAndFormatImages).toHaveBeenCalledWith(
+ req,
+ files,
+ params,
+ { getStrategyFunctions, httpClient: axios },
+ 'agents',
+ );
});
-describe('encodeAndFormat - request memory guard', () => {
- it('gates blob-storage byte pulls and returns [file, base64]', async () => {
- mockGetDownloadStream.mockResolvedValue(Readable.from([Buffer.from('blob-image-bytes')]));
- const file = {
- source: FileSources.s3,
- height: 10,
- width: 10,
- type: 'image/png',
- file_id: 'f-blob',
- filepath: 'bucket/a.png',
- filename: 'a.png',
- bytes: 4321,
- };
-
- const result = await encodeAndFormat(makeReq(), [file], { endpoint: 'openai' });
-
- expect(mockRunGuardedEncode).toHaveBeenCalledTimes(1);
- expect(mockRunGuardedEncode.mock.calls[0][0]).toBe(4321);
-
- const expectedBase64 = Buffer.from('blob-image-bytes').toString('base64');
- expect(result.image_urls).toHaveLength(1);
- expect(result.image_urls[0].image_url.url).toBe(`data:image/png;base64,${expectedBase64}`);
- });
-
- it('gates base64Only URL fetches and returns [file, base64]', async () => {
- mockPrepareImagePayload.mockResolvedValue([
- { source: FileSources.vectordb, type: 'image/png' },
- 'https://images.example/x.png',
- ]);
- axios.get.mockResolvedValue({ data: Buffer.from('url-image-bytes') });
-
- const file = {
- source: FileSources.vectordb,
- height: 10,
- width: 10,
- type: 'image/png',
- file_id: 'f-url',
- filepath: 'remote/x.png',
- filename: 'x.png',
- bytes: 9876,
- };
-
- const result = await encodeAndFormat(makeReq(), [file], { endpoint: 'anthropic' });
-
- expect(mockRunGuardedEncode).toHaveBeenCalledTimes(1);
- expect(mockRunGuardedEncode.mock.calls[0][0]).toBe(9876);
-
- const expectedBase64 = Buffer.from('url-image-bytes').toString('base64');
- expect(result.image_urls).toHaveLength(1);
- expect(result.image_urls[0].source.data).toBe(expectedBase64);
- });
-
- it('does not gate the non-buffering local prepare path', async () => {
- const localBase64 = Buffer.from('local-image').toString('base64');
- mockPrepareImagePayload.mockResolvedValue([
- { source: FileSources.local, type: 'image/png' },
- localBase64,
- ]);
-
- const file = {
- source: FileSources.local,
- height: 10,
- width: 10,
- type: 'image/png',
- file_id: 'f-local',
- filepath: 'local/p.png',
- filename: 'p.png',
- bytes: 555,
- };
-
- const result = await encodeAndFormat(makeReq(), [file], { endpoint: 'openai' });
-
- expect(mockRunGuardedEncode).not.toHaveBeenCalled();
- expect(result.image_urls).toHaveLength(1);
- expect(result.image_urls[0].image_url.url).toBe(`data:image/png;base64,${localBase64}`);
- });
-});
-
-describe('encodeAndFormat - image detail', () => {
- const imageFile = () => ({
- source: FileSources.s3,
+it('encodes canonical storage keys through the built package and the existing CJS entry point', async () => {
+ encodeAndFormatImages.mockImplementation(
+ jest.requireActual('@librechat/api').encodeAndFormatImages,
+ );
+ const bytes = Buffer.from('stored-image-bytes');
+ const getDownloadStream = jest.fn().mockResolvedValue(Readable.from(bytes));
+ const prepareImagePayload = jest.fn();
+ getStrategyFunctions.mockReturnValue({ getDownloadStream, prepareImagePayload });
+ const req = { body: {}, config: {} };
+ const file = {
+ source: 's3',
+ file_id: 'image-1',
+ filename: 'image.png',
+ filepath: 'https://storage.example/image.png?signature=secret',
+ storageKey: 'images/user/image.png',
+ type: 'image/png',
+ bytes: bytes.length,
height: 10,
width: 10,
- type: 'image/png',
- file_id: 'f-detail',
- filepath: 'bucket/a.png',
- filename: 'a.png',
- bytes: 128,
- });
-
- beforeEach(() => {
- mockGetDownloadStream.mockResolvedValue(Readable.from([Buffer.from('image-bytes')]));
- });
-
- it('falls back to auto when no detail is configured anywhere', async () => {
- const result = await encodeAndFormat(makeReq(), [imageFile()], { endpoint: 'openai' });
-
- expect(result.image_urls[0].image_url.detail).toBe('auto');
- });
-
- it('uses the conversation-level detail from the request body', async () => {
- const req = makeReq();
- req.body.imageDetail = 'low';
-
- const result = await encodeAndFormat(req, [imageFile()], { endpoint: 'openai' });
-
- expect(result.image_urls[0].image_url.detail).toBe('low');
- });
-
- it('uses the detail resolved by the caller on routes with no body setting', async () => {
- const result = await encodeAndFormat(makeReq(), [imageFile()], {
- endpoint: 'agents',
- imageDetail: 'high',
- });
-
- expect(result.image_urls[0].image_url.detail).toBe('high');
- });
-
- it('prefers the caller-resolved detail over the request body', async () => {
- const req = makeReq();
- req.body.imageDetail = 'low';
-
- const result = await encodeAndFormat(req, [imageFile()], {
- endpoint: 'agents',
- imageDetail: 'high',
- });
-
- expect(result.image_urls[0].image_url.detail).toBe('high');
- });
+ };
+
+ const result = await encodeAndFormat(req, [file], { endpoint: 'openai' });
+
+ expect(getDownloadStream).toHaveBeenCalledWith(req, file.storageKey);
+ expect(prepareImagePayload).not.toHaveBeenCalled();
+ expect(result.image_urls).toEqual([
+ {
+ type: 'image_url',
+ image_url: { url: `data:image/png;base64,${bytes.toString('base64')}`, detail: 'auto' },
+ },
+ ]);
});
diff --git a/packages/api/src/files/encode/image.spec.ts b/packages/api/src/files/encode/image.spec.ts
new file mode 100644
index 0000000000..f447faedc1
--- /dev/null
+++ b/packages/api/src/files/encode/image.spec.ts
@@ -0,0 +1,246 @@
+import { Readable } from 'node:stream';
+import { FileSources, VisionModes } from 'librechat-data-provider';
+import type { ServerRequest } from '~/types';
+import { AttachmentStorageError, encodeAndFormatImages } from './image';
+import * as memoryGuard from './memoryGuard';
+
+const imageBytes = Buffer.from('image-content-bytes');
+const content = imageBytes.toString('base64');
+const dataUrl = `data:image/png;base64,${content}`;
+const file = {
+ file_id: 'image-1',
+ filepath: 'https://storage.example/image.png?signature=secret',
+ storageKey: 'images/user/image.png',
+ filename: 'image.png',
+ type: 'image/png',
+ bytes: imageBytes.length,
+ height: 10,
+ width: 10,
+ source: FileSources.s3,
+};
+const makeReq = (config: Partial<NonNullable<ServerRequest['config']>> = {}) =>
+ ({ body: {}, config }) as ServerRequest;
+
+describe('encodeAndFormatImages', () => {
+ const getDownloadStream = jest.fn();
+ const prepareImagePayload = jest.fn();
+ const getStrategyFunctions: jest.MockedFunction<
+ Parameters<typeof encodeAndFormatImages>[3]['getStrategyFunctions']
+ > = jest.fn();
+ const httpClient = { get: jest.fn() };
+ const deps = { getStrategyFunctions, httpClient };
+
+ beforeEach(() => {
+ jest.resetAllMocks();
+ getDownloadStream.mockImplementation(async () => Readable.from(imageBytes));
+ prepareImagePayload.mockImplementation(async (_req, image) => [image, content]);
+ getStrategyFunctions.mockImplementation(() => ({ getDownloadStream, prepareImagePayload }));
+ httpClient.get.mockResolvedValue({ data: imageBytes });
+ jest.spyOn(memoryGuard, 'runGuardedEncode');
+ });
+
+ afterEach(() => jest.restoreAllMocks());
+
+ it.each([FileSources.s3, FileSources.cloudfront, FileSources.azure_blob, FileSources.firebase])(
+ 'reads %s by canonical key without entering the legacy payload path',
+ async (source) => {
+ const result = await encodeAndFormatImages(makeReq(), [{ ...file, source }], {}, deps);
+
+ expect(result.image_urls).toEqual([
+ { type: 'image_url', image_url: { url: dataUrl, detail: 'auto' } },
+ ]);
+ expect(result.files).toEqual([
+ expect.objectContaining({ file_id: file.file_id, height: 10, width: 10, embedded: false }),
+ ]);
+ expect(result.files[0]).not.toHaveProperty('storageKey');
+ expect(getDownloadStream).toHaveBeenCalledWith(expect.anything(), file.storageKey);
+ expect(memoryGuard.runGuardedEncode).toHaveBeenCalledWith(file.bytes, expect.any(Function));
+ expect(prepareImagePayload).not.toHaveBeenCalled();
+ expect(httpClient.get).not.toHaveBeenCalled();
+ },
+ );
+
+ it('uses the legacy filepath when no canonical key was stored', async () => {
+ await encodeAndFormatImages(makeReq(), [{ ...file, storageKey: undefined }], {}, deps);
+ expect(getDownloadStream).toHaveBeenCalledWith(expect.anything(), file.filepath);
+ });
+
+ it('returns an empty result without acquiring a strategy for absent files', async () => {
+ await expect(encodeAndFormatImages(makeReq(), undefined, {}, deps)).resolves.toEqual({
+ files: [],
+ image_urls: [],
+ });
+ await expect(encodeAndFormatImages(makeReq(), [], {}, deps)).resolves.toEqual({
+ files: [],
+ image_urls: [],
+ });
+ expect(getStrategyFunctions).not.toHaveBeenCalled();
+ });
+
+ it('keeps metadata-only attachments without reading storage', async () => {
+ const result = await encodeAndFormatImages(
+ makeReq(),
+ [{ ...file, height: undefined }],
+ {},
+ deps,
+ );
+ expect(result.files).toHaveLength(1);
+ expect(result.image_urls).toEqual([]);
+ expect(getStrategyFunctions).not.toHaveBeenCalled();
+ });
+
+ it('keeps metadata when a stored image has no download reference', async () => {
+ const result = await encodeAndFormatImages(
+ makeReq(),
+ [{ ...file, filepath: '', storageKey: undefined }],
+ {},
+ deps,
+ );
+ expect(result.files).toHaveLength(1);
+ expect(result.image_urls).toEqual([]);
+ expect(getDownloadStream).not.toHaveBeenCalled();
+ expect(prepareImagePayload).not.toHaveBeenCalled();
+ });
+
+ it('preserves the missing-object error without falling back to an external URL', async () => {
+ getDownloadStream.mockRejectedValue({ name: 'NoSuchKey' });
+ await expect(encodeAndFormatImages(makeReq(), [file], {}, deps)).rejects.toMatchObject({
+ code: 'ATTACHMENT_OBJECT_NOT_FOUND',
+ fileId: file.file_id,
+ });
+ expect(prepareImagePayload).not.toHaveBeenCalled();
+ expect(httpClient.get).not.toHaveBeenCalled();
+ });
+
+ it('discards buffered image bytes and hides storage error details', async () => {
+ const failure = new Error('private storage path');
+ getDownloadStream.mockResolvedValue(
+ new Readable({
+ read() {
+ this.push(imageBytes);
+ this.destroy(failure);
+ },
+ }),
+ );
+ await expect(encodeAndFormatImages(makeReq(), [file], {}, deps)).rejects.toEqual(
+ new AttachmentStorageError(),
+ );
+ expect(failure).not.toHaveProperty('bufferedData');
+ expect(prepareImagePayload).not.toHaveBeenCalled();
+ expect(httpClient.get).not.toHaveBeenCalled();
+ });
+
+ it.each([FileSources.local, undefined])(
+ 'keeps the unguarded local path for %s',
+ async (source) => {
+ const result = await encodeAndFormatImages(makeReq(), [{ ...file, source }], {}, deps);
+ expect(result.image_urls).toEqual([
+ { type: 'image_url', image_url: { url: dataUrl, detail: 'auto' } },
+ ]);
+ expect(prepareImagePayload).toHaveBeenCalled();
+ expect(getDownloadStream).not.toHaveBeenCalled();
+ expect(memoryGuard.runGuardedEncode).not.toHaveBeenCalled();
+ },
+ );
+
+ it('keeps legacy external URLs for endpoints that accept them', async () => {
+ prepareImagePayload.mockImplementation(async (_req, image) => [image, file.filepath]);
+ const result = await encodeAndFormatImages(
+ makeReq(),
+ [{ ...file, source: FileSources.openai }],
+ { endpoint: 'openai' },
+ deps,
+ );
+ expect(result.image_urls).toEqual([
+ { type: 'image_url', image_url: { url: file.filepath, detail: 'auto' } },
+ ]);
+ expect(httpClient.get).not.toHaveBeenCalled();
+ expect(memoryGuard.runGuardedEncode).not.toHaveBeenCalled();
+ });
+
+ it('guards legacy URL downloads for base64-only endpoints', async () => {
+ prepareImagePayload.mockImplementation(async (_req, image) => [image, file.filepath]);
+ const result = await encodeAndFormatImages(
+ makeReq(),
+ [{ ...file, source: FileSources.openai }],
+ { endpoint: 'anthropic' },
+ deps,
+ );
+ expect(result.image_urls).toEqual([
+ { type: 'image', source: { type: 'base64', media_type: file.type, data: content } },
+ ]);
+ expect(httpClient.get).toHaveBeenCalledWith(file.filepath, { responseType: 'arraybuffer' });
+ expect(memoryGuard.runGuardedEncode).toHaveBeenCalledWith(file.bytes, expect.any(Function));
+ });
+
+ it('rejects unsupported legacy strategies instead of silently dropping images', async () => {
+ getStrategyFunctions.mockReturnValue({ getDownloadStream });
+ await expect(
+ encodeAndFormatImages(makeReq(), [{ ...file, source: FileSources.openai }], {}, deps),
+ ).rejects.toThrow('Encoding function not implemented for openai');
+ });
+
+ it.each([
+ [
+ 'google',
+ VisionModes.generative,
+ { type: 'image_url', inlineData: { mimeType: file.type, data: content } },
+ ],
+ ['google', undefined, { type: 'image_url', image_url: dataUrl }],
+ [
+ 'anthropic',
+ undefined,
+ { type: 'image', source: { type: 'base64', media_type: file.type, data: content } },
+ ],
+ [
+ 'anthropic',
+ VisionModes.agents,
+ { type: 'image_url', image_url: { url: dataUrl, detail: 'auto' } },
+ ],
+ ])('preserves the %s payload in mode %s', async (provider, mode, expected) => {
+ const result = await encodeAndFormatImages(makeReq(), [file], { provider }, deps, mode);
+ expect(result.image_urls).toEqual([expected]);
+ });
+
+ it.each([
+ [undefined, undefined, 'auto'],
+ ['low', undefined, 'low'],
+ [undefined, 'high', 'high'],
+ ['low', 'high', 'high'],
+ ] as const)(
+ 'resolves body detail %s and caller detail %s',
+ async (bodyDetail, imageDetail, expected) => {
+ const req = makeReq();
+ req.body.imageDetail = bodyDetail;
+ const result = await encodeAndFormatImages(req, [file], { imageDetail }, deps);
+ expect(result.image_urls).toEqual([
+ { type: 'image_url', image_url: { url: dataUrl, detail: expected } },
+ ]);
+ },
+ );
+
+ it('reuses each strategy and preserves order across storage and local images', async () => {
+ const files = [
+ file,
+ { ...file, file_id: 'local', source: FileSources.local },
+ { ...file, file_id: 'stored-2' },
+ ];
+ const result = await encodeAndFormatImages(makeReq(), files, {}, deps);
+ expect(result.files.map((entry) => entry.file_id)).toEqual(files.map((entry) => entry.file_id));
+ expect(result.image_urls).toHaveLength(3);
+ expect(getStrategyFunctions).toHaveBeenCalledTimes(2);
+ expect(getDownloadStream).toHaveBeenCalledTimes(2);
+ expect(prepareImagePayload).toHaveBeenCalledTimes(1);
+ });
+
+ it.each([
+ { endpoint: 'anthropic' },
+ { provider: 'anthropic' },
+ { provider: 'openai', endpoint: 'anthropic' },
+ ])('resolves the configured size limit for %j', async (params) => {
+ const req = makeReq({ fileConfig: { endpoints: { anthropic: { fileSizeLimit: 0.000001 } } } });
+ await expect(encodeAndFormatImages(req, [file], params, deps)).rejects.toThrow(
+ 'Image validation failed for image.png: Image file size',
+ );
+ });
+});
diff --git a/packages/api/src/files/encode/image.ts b/packages/api/src/files/encode/image.ts
new file mode 100644
index 0000000000..bcd486a54d
--- /dev/null
+++ b/packages/api/src/files/encode/image.ts
@@ -0,0 +1,221 @@
+import {
+ FileSources,
+ VisionModes,
+ ImageDetail,
+ ContentTypes,
+ EModelEndpoint,
+ mergeFileConfig,
+ getEndpointFileConfig,
+} from 'librechat-data-provider';
+import type { IMongoFile } from '@librechat/data-schemas';
+import type { Agents } from 'librechat-data-provider';
+import type { AxiosInstance } from 'axios';
+import type { ServerRequest, StrategyFunctions } from '~/types';
+import { getFileStream, isAttachmentObjectNotFoundError } from './utils';
+import { validateImage } from '~/files/validation';
+import { runGuardedEncode } from './memoryGuard';
+import { logAxiosError } from '~/utils/axios';
+
+type ImageEncodingFile = Pick<
+ IMongoFile,
+ | 'file_id'
+ | 'temp_file_id'
+ | 'filepath'
+ | 'storageKey'
+ | 'filename'
+ | 'type'
+ | 'height'
+ | 'width'
+ | 'embedded'
+ | 'metadata'
+> &
+ Partial<Pick<IMongoFile, 'source' | 'bytes'>>;
+
+type ImageEntry = [ImageEncodingFile, string | null];
+
+interface ImageStrategy extends StrategyFunctions {
+ prepareImagePayload?: (
+ req: ServerRequest,
+ file: ImageEncodingFile,
+ ) => Promise<[ImageEncodingFile, string]>;
+}
+
+interface ImageEncodingDependencies {
+ getStrategyFunctions: (source: string) => ImageStrategy;
+ httpClient: Pick<AxiosInstance, 'get'>;
+}
+
+interface ImageResult {
+ files: Array<
+ Pick<
+ ImageEncodingFile,
+ 'file_id' | 'filepath' | 'filename' | 'type' | 'height' | 'width' | 'embedded' | 'metadata'
+ >
+ >;
+ image_urls: Array<
+ | Agents.MessageContentImageUrl
+ | { type: ContentTypes.IMAGE_URL; inlineData: { mimeType: string; data: string } }
+ | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } }
+ >;
+}
+
+const base64Only = new Set<string>([
+ EModelEndpoint.google,
+ EModelEndpoint.anthropic,
+ 'Ollama',
+ 'ollama',
+ EModelEndpoint.bedrock,
+]);
+
+const blobStorageSources = new Set<string>([
+ FileSources.azure_blob,
+ FileSources.s3,
+ FileSources.firebase,
+ FileSources.cloudfront,
+]);
+
+export class AttachmentStorageError extends Error {
+ readonly code = 'ATTACHMENT_STORAGE_ERROR';
+
+ constructor() {
+ super('An attached file could not be read from storage. Try again or upload it again.');
+ this.name = 'AttachmentStorageError';
+ }
+}
+
+/** Owns source selection, guarded reads, validation and provider-specific image formatting. */
+export async function encodeAndFormatImages(
+ req: ServerRequest,
+ files: ImageEncodingFile[] | null | undefined,
+ params: { provider?: string; endpoint?: string; imageDetail?: Agents.ImageDetail },
+ { getStrategyFunctions, httpClient }: ImageEncodingDependencies,
+ mode?: string,
+): Promise<ImageResult> {
+ const { provider, endpoint } = params;
+ const effectiveEndpoint = endpoint ?? provider;
+ const promises: Array<ImageEntry | Promise<ImageEntry>> = [];
+ const encodingMethods: Record<string, ImageStrategy> = {};
+ const result: ImageResult = { files: [], image_urls: [] };
+
+ if (!files?.length) {
+ return result;
+ }
+
+ for (const file of files) {
+ const source = file.source ?? FileSources.local;
+ if (!file.height) {
+ promises.push([file, null]);
+ continue;
+ }
+
+ if (blobStorageSources.has(source)) {
+ try {
+ const processedFile = await runGuardedEncode(file.bytes ?? 0, () =>
+ getFileStream(req, file, encodingMethods, getStrategyFunctions),
+ );
+ promises.push([file, processedFile?.content ?? null]);
+ } catch (error) {
+ if (isAttachmentObjectNotFoundError(error)) {
+ throw error;
+ }
+ if (typeof error === 'object' && error != null && 'bufferedData' in error) {
+ delete (error as { bufferedData?: unknown }).bufferedData;
+ }
+ throw new AttachmentStorageError();
+ }
+ continue;
+ }
+
+ if (!encodingMethods[source]) {
+ encodingMethods[source] = getStrategyFunctions(source);
+ }
+ const preparePayload = encodingMethods[source].prepareImagePayload;
+ if (!preparePayload) {
+ throw new Error(`Encoding function not implemented for ${source}`);
+ }
+
+ if (source !== FileSources.local && effectiveEndpoint && base64Only.has(effectiveEndpoint)) {
+ const entry = await runGuardedEncode<ImageEntry>(file.bytes ?? 0, async () => {
+ const [preparedFile, imageURL] = await preparePayload(req, file);
+ try {
+ const response = await httpClient.get<ArrayBuffer>(imageURL, {
+ responseType: 'arraybuffer',
+ });
+ return [preparedFile, Buffer.from(response.data).toString('base64')];
+ } catch (error) {
+ const message = 'Error fetching image to convert to base64';
+ throw new Error(logAxiosError({ message, error }));
+ }
+ });
+ promises.push(entry);
+ continue;
+ }
+ promises.push(preparePayload(req, file));
+ }
+
+ const detail = params.imageDetail ?? req.body.imageDetail ?? ImageDetail.auto;
+ const formattedImages = await Promise.all(promises);
+ let configuredFileSizeLimit: number | undefined;
+ if (req.config?.fileConfig) {
+ const fileConfig = mergeFileConfig(req.config.fileConfig);
+ const endpointConfig = getEndpointFileConfig({
+ fileConfig,
+ endpoint: effectiveEndpoint,
+ });
+ configuredFileSizeLimit = endpointConfig?.fileSizeLimit;
+ }
+
+ for (const [file, imageContent] of formattedImages) {
+ const fileMetadata: ImageResult['files'][number] = {
+ type: file.type,
+ file_id: file.file_id,
+ filepath: file.filepath,
+ filename: file.filename,
+ embedded: !!file.embedded,
+ metadata: file.metadata,
+ };
+ if (file.height && file.width) {
+ fileMetadata.height = file.height;
+ fileMetadata.width = file.width;
+ }
+ result.files.push(fileMetadata);
+
+ if (!imageContent) {
+ continue;
+ }
+
+ const isURL = imageContent.startsWith('http');
+ if (file.height && file.width && !isURL) {
+ const imageBuffer = Buffer.from(imageContent, 'base64');
+ const validation = await validateImage(
+ imageBuffer,
+ imageBuffer.length,
+ effectiveEndpoint ?? '',
+ configuredFileSizeLimit,
+ );
+ if (!validation.isValid) {
+ throw new Error(`Image validation failed for ${file.filename}: ${validation.error}`);
+ }
+ }
+
+ const url = isURL ? imageContent : `data:${file.type};base64,${imageContent}`;
+ if (mode === VisionModes.agents) {
+ result.image_urls.push({ type: ContentTypes.IMAGE_URL, image_url: { url, detail } });
+ } else if (effectiveEndpoint === EModelEndpoint.google && mode === VisionModes.generative) {
+ result.image_urls.push({
+ type: ContentTypes.IMAGE_URL,
+ inlineData: { mimeType: file.type, data: imageContent },
+ });
+ } else if (effectiveEndpoint === EModelEndpoint.google) {
+ result.image_urls.push({ type: ContentTypes.IMAGE_URL, image_url: url });
+ } else if (effectiveEndpoint === EModelEndpoint.anthropic) {
+ result.image_urls.push({
+ type: 'image',
+ source: { type: 'base64', media_type: file.type, data: imageContent },
+ });
+ } else {
+ result.image_urls.push({ type: ContentTypes.IMAGE_URL, image_url: { url, detail } });
+ }
+ }
+ return result;
+}
diff --git a/packages/api/src/files/encode/index.ts b/packages/api/src/files/encode/index.ts
index 447ad527c8..343ef07726 100644
--- a/packages/api/src/files/encode/index.ts
+++ b/packages/api/src/files/encode/index.ts
@@ -1,5 +1,6 @@
export * from './audio';
export * from './document';
+export * from './image';
export * from './video';
export * from './memoryGuard';
export * from './utils';
diff --git a/packages/api/src/files/encode/utils.spec.ts b/packages/api/src/files/encode/utils.spec.ts
index c2090055ed..24367409c7 100644
--- a/packages/api/src/files/encode/utils.spec.ts
+++ b/packages/api/src/files/encode/utils.spec.ts
@@ -1,6 +1,5 @@
import { Readable } from 'node:stream';
-import type { IMongoFile } from '@librechat/data-schemas';
-import type { ServerRequest, StrategyFunctions } from '~/types';
+import type { ServerRequest } from '~/types';
import { AttachmentObjectNotFoundError, getFileStream } from './utils';
const file = {
@@ -10,7 +9,7 @@ const file = {
type: 'application/pdf',
bytes: 4,
source: 's3',
-} as IMongoFile;
+};
describe('getFileStream', () => {
it('maps a missing storage object to a user-actionable attachment error', async () => {
@@ -20,12 +19,7 @@ describe('getFileStream', () => {
});
await expect(
- getFileStream(
- {} as ServerRequest,
- file,
- {},
- () => ({ getDownloadStream }) as StrategyFunctions,
- ),
+ getFileStream({} as ServerRequest, file, {}, () => ({ getDownloadStream })),
).rejects.toEqual(
expect.objectContaining<Partial<AttachmentObjectNotFoundError>>({
code: 'ATTACHMENT_OBJECT_NOT_FOUND',
@@ -40,12 +34,7 @@ describe('getFileStream', () => {
const getDownloadStream = jest.fn().mockRejectedValue(storageError);
await expect(
- getFileStream(
- {} as ServerRequest,
- file,
- {},
- () => ({ getDownloadStream }) as StrategyFunctions,
- ),
+ getFileStream({} as ServerRequest, file, {}, () => ({ getDownloadStream })),
).rejects.toMatchObject({ code: 'ATTACHMENT_OBJECT_NOT_FOUND', fileId: 'file-1' });
},
);
@@ -55,12 +44,7 @@ describe('getFileStream', () => {
const getDownloadStream = jest.fn().mockRejectedValue(failure);
await expect(
- getFileStream(
- {} as ServerRequest,
- file,
- {},
- () => ({ getDownloadStream }) as StrategyFunctions,
- ),
+ getFileStream({} as ServerRequest, file, {}, () => ({ getDownloadStream })),
).rejects.toBe(failure);
});
@@ -68,12 +52,35 @@ describe('getFileStream', () => {
const getDownloadStream = jest.fn().mockResolvedValue(Readable.from(Buffer.from('data')));
await expect(
- getFileStream(
- {} as ServerRequest,
- file,
- {},
- () => ({ getDownloadStream }) as StrategyFunctions,
- ),
+ getFileStream({} as ServerRequest, file, {}, () => ({ getDownloadStream })),
).resolves.toMatchObject({ content: Buffer.from('data').toString('base64') });
});
+
+ it.each([
+ '',
+ 'https://minio.example.com/librechat/uploads/user%201/image%20one.png?X-Amz-Credential=secret&X-Amz-Signature=signed',
+ ])('reads the canonical storage key with filepath %s', async (filepath) => {
+ const getDownloadStream = jest.fn().mockResolvedValue(Readable.from(Buffer.from('image')));
+ const storedFile = {
+ ...file,
+ filepath,
+ storageKey: 'uploads/user 1/image one.png',
+ };
+ const req = {} as ServerRequest;
+
+ await getFileStream(req, storedFile, {}, () => ({ getDownloadStream }));
+
+ expect(getDownloadStream).toHaveBeenCalledWith(req, storedFile.storageKey);
+ });
+
+ it('passes the legacy filepath when no storage key was recorded', async () => {
+ const getDownloadStream = jest.fn().mockResolvedValue(Readable.from(Buffer.from('image')));
+ const legacyUrl =
+ 'https://minio.example.com/librechat/uploads/user%201/image.png?X-Amz-Signature=signed';
+ const req = {} as ServerRequest;
+
+ await getFileStream(req, { ...file, filepath: legacyUrl }, {}, () => ({ getDownloadStream }));
+
+ expect(getDownloadStream).toHaveBeenCalledWith(req, legacyUrl);
+ });
});
diff --git a/packages/api/src/files/encode/utils.ts b/packages/api/src/files/encode/utils.ts
index f0e63cbad0..7d7ac21a3a 100644
--- a/packages/api/src/files/encode/utils.ts
+++ b/packages/api/src/files/encode/utils.ts
@@ -1,8 +1,8 @@
import getStream from 'get-stream';
import { Providers } from '@librechat/agents';
import { FileSources, mergeFileConfig, getEndpointFileConfig } from 'librechat-data-provider';
-import type { IMongoFile } from '@librechat/data-schemas';
import type { ServerRequest, StrategyFunctions, ProcessedFile } from '~/types';
+import type { StoredFileRef } from '~/storage/path';
import { resolveDownloadPath } from '~/storage/path';
export class AttachmentObjectNotFoundError extends Error {
@@ -76,15 +76,15 @@ export const getConfiguredFileSizeLimit = (
* @param file - File object to process
* @param encodingMethods - Cache of encoding methods by source
* @param getStrategyFunctions - Function to get strategy functions for a source
- * @returns Processed file with content and metadata, or null if filepath missing
+ * @returns Processed file with content and metadata, or null if no download reference exists
*/
-export async function getFileStream(
+export async function getFileStream<T extends ProcessedFile['metadata'] & StoredFileRef>(
req: ServerRequest,
- file: IMongoFile,
+ file: T,
encodingMethods: Record<string, StrategyFunctions>,
getStrategyFunctions: (source: string) => StrategyFunctions,
-): Promise<ProcessedFile | null> {
- if (!file?.filepath) {
+): Promise<ProcessedFile<T> | null> {
+ if (!file?.filepath && !file?.storageKey) {
return null;
}
diff --git a/packages/api/src/storage/s3/__tests__/crud.test.ts b/packages/api/src/storage/s3/__tests__/crud.test.ts
index d1c12e8371..b9c6e5e2ed 100644
--- a/packages/api/src/storage/s3/__tests__/crud.test.ts
+++ b/packages/api/src/storage/s3/__tests__/crud.test.ts
@@ -1485,10 +1485,12 @@ describe('S3 CRUD', () => {
it('handles URL with query parameters', async () => {
const { extractKeyFromS3Url } = await import('../crud');
- const key = extractKeyFromS3Url(
- 'https://bucket.s3.amazonaws.com/images/user123/file.png?X-Amz-Signature=abc',
- );
+ const signedUrl =
+ 'https://bucket.s3.amazonaws.com/images/user123/file.png?X-Amz-Signature=abc';
+ const key = extractKeyFromS3Url(signedUrl);
expect(key).toBe('images/user123/file.png');
+ expect(JSON.stringify((logger.debug as jest.Mock).mock.calls)).not.toContain(signedUrl);
+ expect(JSON.stringify((logger.debug as jest.Mock).mock.calls)).not.toContain(key);
});
it('decodes percent-encoded keys from virtual-hosted-style URLs', async () => {
@@ -1606,12 +1608,12 @@ describe('S3 CRUD', () => {
expect(result).toBe(malformedUrl);
});
- it('strips bucket from custom endpoint URLs (MinIO, R2)', async () => {
+ it('decodes a signed path-style custom endpoint URL for a legacy record', async () => {
const { extractKeyFromS3Url } = await import('../crud');
const key = extractKeyFromS3Url(
- 'https://minio.example.com/test-bucket/images/user123/file.jpg',
+ 'https://minio.example.com/test-bucket/images/user123/my%20file.jpg?X-Amz-Credential=secret&X-Amz-Signature=signed',
);
- expect(key).toBe('images/user123/file.jpg');
+ expect(key).toBe('images/user123/my file.jpg');
});
});
diff --git a/packages/api/src/storage/s3/crud.ts b/packages/api/src/storage/s3/crud.ts
index b818307795..5ddcf9cfa7 100644
--- a/packages/api/src/storage/s3/crud.ts
+++ b/packages/api/src/storage/s3/crud.ts
@@ -51,6 +51,7 @@ import {
assertPathSegment,
sanitizeContentDispositionFilename,
} from '~/storage/validation';
+import { getSafeErrorMetadata } from '~/utils/errors';
import { initializeS3 } from '~/cdn/s3';
import { deleteRagFile } from '~/files';
import { s3Config } from './s3Config';
@@ -653,7 +654,7 @@ function decodeKeyFromUrlPath(key: string): string {
try {
return decodeURIComponent(key);
} catch {
- logger.warn(`[extractKeyFromS3Url] Could not decode key, using it as-is: ${key}`);
+ logger.warn('[extractKeyFromS3Url] Could not decode key, using it as-is');
return key;
}
}
@@ -681,11 +682,7 @@ export function extractKeyFromS3Url(fileUrlOrKey: string): string {
1;
const key = decodeKeyFromUrlPath(url.pathname.substring(startPos));
if (!key) {
- logger.warn(
- `[extractKeyFromS3Url] Extracted key is empty for endpoint path-style URL: ${fileUrlOrKey}`,
- );
- } else {
- logger.debug(`[extractKeyFromS3Url] fileUrlOrKey: ${fileUrlOrKey}, Extracted key: ${key}`);
+ logger.warn('[extractKeyFromS3Url] Extracted key is empty for endpoint path-style URL');
}
return key;
}
@@ -699,44 +696,19 @@ export function extractKeyFromS3Url(fileUrlOrKey: string): string {
if (firstSlashIndex > 0) {
const key = decodeKeyFromUrlPath(pathname.substring(firstSlashIndex + 1));
if (key === '') {
- logger.warn(
- `[extractKeyFromS3Url] Extracted key is empty after removing bucket name from URL: ${fileUrlOrKey}`,
- );
- } else {
- logger.debug(
- `[extractKeyFromS3Url] fileUrlOrKey: ${fileUrlOrKey}, Extracted key: ${key}`,
- );
+ logger.warn('[extractKeyFromS3Url] Extracted key is empty after removing bucket name');
}
return key;
}
- logger.warn(
- `[extractKeyFromS3Url] Unable to extract key from path-style URL: ${fileUrlOrKey}`,
- );
+ logger.warn('[extractKeyFromS3Url] Unable to extract key from path-style URL');
return '';
}
const key = decodeKeyFromUrlPath(pathname);
- logger.debug(`[extractKeyFromS3Url] fileUrlOrKey: ${fileUrlOrKey}, Extracted key: ${key}`);
- return key;
- } catch (error) {
- if (fileUrlOrKey.startsWith('http://') || fileUrlOrKey.startsWith('https://')) {
- logger.error(
- `[extractKeyFromS3Url] Error parsing URL: ${fileUrlOrKey}, Error: ${(error as Error).message}`,
- );
- } else {
- logger.debug(`[extractKeyFromS3Url] Non-URL input, using fallback: ${fileUrlOrKey}`);
- }
-
- const parts = fileUrlOrKey.split('/');
- if (parts.length >= 3 && !fileUrlOrKey.startsWith('http') && !fileUrlOrKey.startsWith('/')) {
- return fileUrlOrKey;
- }
-
- const key = fileUrlOrKey.startsWith('/') ? fileUrlOrKey.substring(1) : fileUrlOrKey;
- logger.debug(
- `[extractKeyFromS3Url] FALLBACK. fileUrlOrKey: ${fileUrlOrKey}, Extracted key: ${key}`,
- );
return key;
+ } catch {
+ logger.error('[extractKeyFromS3Url] Error parsing URL');
+ return fileUrlOrKey;
}
}
@@ -893,11 +865,11 @@ export async function getS3FileStream(
const data = await s3.send(new GetObjectCommand(params), { abortSignal: signal });
if (!data.Body) {
- throw new Error(`[getS3FileStream] S3 response body is empty for key: ${Key}`);
+ throw new Error('[getS3FileStream] S3 response body is empty');
}
return data.Body as Readable;
} catch (error) {
- logger.error('[getS3FileStream] Error retrieving S3 file stream:', error);
+ logger.error('[getS3FileStream] Error retrieving S3 file stream', getSafeErrorMetadata(error));
throw error;
}
}
diff --git a/packages/api/src/types/files.ts b/packages/api/src/types/files.ts
index fa708d7c35..b49a1a1f90 100644
--- a/packages/api/src/types/files.ts
+++ b/packages/api/src/types/files.ts
@@ -159,8 +159,8 @@ export interface AudioResult {
}>;
}
-export interface ProcessedFile {
- file: IMongoFile;
+export interface ProcessedFile<T = IMongoFile> {
+ file: T;
content: string;
metadata: {
file_id: string;
diff --git a/packages/api/src/types/http.ts b/packages/api/src/types/http.ts
index 3c077ace54..a5f6121606 100644
--- a/packages/api/src/types/http.ts
+++ b/packages/api/src/types/http.ts
@@ -2,6 +2,7 @@ import type {
CodeApprovalMode,
CodeWorkspaceSelection,
TEndpointOption,
+ Agents,
} from 'librechat-data-provider';
import type { IUser, AppConfig, IConversation } from '@librechat/data-schemas';
import type { Request } from 'express';
@@ -18,6 +19,7 @@ export type RequestBody = {
endpoint?: string;
endpointType?: string;
model?: string;
+ imageDetail?: Agents.ImageDetail;
key?: string;
endpointOption?: Partial<TEndpointOption>;
/** Browser IANA timezone used to resolve local-time prompt variables (e.g. `{{current_datetime}}`). */
diff --git a/packages/api/src/utils/errors.spec.ts b/packages/api/src/utils/errors.spec.ts
index ebe8e16b3a..fde1e223c2 100644
--- a/packages/api/src/utils/errors.spec.ts
+++ b/packages/api/src/utils/errors.spec.ts
@@ -1,4 +1,4 @@
-import { getSafeErrorMetadata, isAbortError } from './errors';
+import { getSafeErrorMetadata, getSafeErrorText, isAbortError } from './errors';
describe('getSafeErrorMetadata', () => {
it('keeps bounded diagnostic fields without serializing raw provider data', () => {
@@ -52,6 +52,84 @@ describe('getSafeErrorMetadata', () => {
});
});
+describe('getSafeErrorText', () => {
+ const signedUrl =
+ 'https://minio.example.com/bucket/images/user123/photo.png?X-Amz-Credential=AKIA123&X-Amz-Signature=deadbeef';
+
+ it('keeps the origin of a signed storage URL and drops its path and signature', () => {
+ const text = getSafeErrorText(new Error(`Access denied for ${signedUrl}`));
+
+ expect(text).toContain('https://minio.example.com/[redacted]');
+ expect(text).not.toContain('X-Amz-Signature');
+ expect(text).not.toContain('deadbeef');
+ expect(text).not.toContain('bucket/images/user123');
+ });
+
+ it('preserves the description and stack an operator needs to place the failure', () => {
+ const text = getSafeErrorText(new Error('No agent found for the requested endpoint'));
+
+ expect(text).toContain('Error: No agent found for the requested endpoint');
+ expect(text).toContain('errors.spec.ts');
+ });
+
+ it('redacts every URL an SDK error folds into its stack', () => {
+ const error = new Error(`upload failed: ${signedUrl}`);
+ error.stack = `Error: upload failed: ${signedUrl}\n at send (/app/api/s3.js:1:1)`;
+
+ const text = getSafeErrorText(error);
+
+ expect(text).not.toContain('deadbeef');
+ expect(text).toContain('at send (/app/api/s3.js:1:1)');
+ });
+
+ it('keeps file:// stack frames readable', () => {
+ const error = new Error('boom');
+ error.stack = 'Error: boom\n at run (file:///app/api/server.js:10:5)';
+
+ expect(getSafeErrorText(error)).toContain('file:///app/api/server.js:10:5');
+ });
+
+ it('redacts bearer credentials echoed into a message', () => {
+ const error = new Error('request rejected: Bearer sk-live-abcdef123456');
+
+ const text = getSafeErrorText(error);
+
+ expect(text).toContain('Bearer [redacted]');
+ expect(text).not.toContain('sk-live-abcdef123456');
+ });
+
+ it('describes an error-like object that carries no stack', () => {
+ expect(getSafeErrorText({ name: 'RestError', message: `blob read failed ${signedUrl}` })).toBe(
+ 'RestError: blob read failed https://minio.example.com/[redacted]',
+ );
+ });
+
+ it('survives a value whose accessors throw', () => {
+ const hostile = new Proxy(
+ {},
+ {
+ get() {
+ throw new Error('accessor exploded');
+ },
+ },
+ );
+
+ expect(getSafeErrorText(hostile)).toBe('UnknownError');
+ });
+
+ it('tolerates non-object values', () => {
+ expect(getSafeErrorText(undefined)).toBe('UnknownError');
+ expect(getSafeErrorText(42)).toBe('UnknownError');
+ expect(getSafeErrorText(`failed at ${signedUrl}`)).toBe(
+ 'failed at https://minio.example.com/[redacted]',
+ );
+ });
+
+ it('bounds the text a very long error can write into the log', () => {
+ expect(getSafeErrorText(new Error('x'.repeat(9000))).length).toBeLessThanOrEqual(2000);
+ });
+});
+
describe('isAbortError', () => {
it('recognizes the DOMException a bare abort() produces', () => {
const controller = new AbortController();
diff --git a/packages/api/src/utils/errors.ts b/packages/api/src/utils/errors.ts
index 897cf58f32..56eaae7813 100644
--- a/packages/api/src/utils/errors.ts
+++ b/packages/api/src/utils/errors.ts
@@ -39,6 +39,64 @@ export function getSafeErrorMetadata(error: unknown): SafeErrorMetadata {
};
}
+const MAX_SAFE_ERROR_TEXT = 2000;
+
+function redactUrl(match: string): string {
+ try {
+ const url = new URL(match);
+ return `${url.protocol}//${url.host}/[redacted]`;
+ } catch {
+ return '[url]';
+ }
+}
+
+function redactSecrets(value: string): string {
+ return value
+ .replace(/\b(?!file:)[a-z][a-z0-9+.-]*:\/\/\S+/gi, redactUrl)
+ .replace(/\b(bearer|basic)\s+\S+/gi, '$1 [redacted]');
+}
+
+/**
+ * The request-boundary counterpart to {@link getSafeErrorMetadata}: the error's own
+ * description and stack, with every URL reduced to its origin and bearer credentials
+ * removed. A signed storage URL carries the object path and signature in the parts
+ * that are dropped, while the origin is what an operator needs to place the failure.
+ *
+ * Returned as text because the caller must log it inside the message and pass no
+ * winston metadata: metadata arms `format.splat()` and promotes an SDK error's own
+ * enumerable properties — `request.url`, `config`, `response.headers` — onto the
+ * record, which is the wider leak an error object causes at a log site.
+ *
+ * Use this where a handler catches every failure on a route and the class of error is
+ * not known ahead of time. Prefer `getSafeErrorMetadata` where the error may echo
+ * submitted content, such as a provider response body.
+ */
+export function getSafeErrorText(error: unknown): string {
+ if (typeof error === 'string') {
+ return redactSecrets(error).slice(0, MAX_SAFE_ERROR_TEXT);
+ }
+
+ if (error == null || typeof error !== 'object') {
+ return 'UnknownError';
+ }
+
+ const stack = readProperty(error, 'stack');
+ if (typeof stack === 'string' && stack.length > 0) {
+ return redactSecrets(stack).slice(0, MAX_SAFE_ERROR_TEXT);
+ }
+
+ const name = readProperty(error, 'name');
+ const message = readProperty(error, 'message');
+ const described = [
+ typeof name === 'string' && name.length > 0 ? name : 'UnknownError',
+ typeof message === 'string' && message.length > 0 ? message : undefined,
+ ]
+ .filter(Boolean)
+ .join(': ');
+
+ return redactSecrets(described).slice(0, MAX_SAFE_ERROR_TEXT);
+}
+
/**
* Whether a caught error is a cancellation rather than a genuine failure.
*