danny-avila/LibreChat · error · Error

Failed to get download stream for image file

Error message

Failed to get download stream for image file

What it means

Thrown when getDownloadStream(req, imageFile.filepath) resolves to a falsy value. The strategy lookup succeeded and the method exists, but the underlying storage call did not return a usable stream — typically because the object/file does not exist at the given path or permissions block the read.

Source

Thrown at api/app/clients/tools/structured/OpenAIImageTools.js:317

        let stream;
        /** @type {NodeStreamDownloader<File>} */
        let getDownloadStream;
        const source = imageFile.source || appFileStrategy;
        if (!source) {
          throw new Error('No source found for image file');
        }
        if (streamMethods[source]) {
          getDownloadStream = streamMethods[source];
        } else {
          ({ getDownloadStream } = getStrategyFunctions(source));
          streamMethods[source] = getDownloadStream;
        }
        if (!getDownloadStream) {
          throw new Error(`No download stream method found for source: ${source}`);
        }
        stream = await getDownloadStream(req, imageFile.filepath);
        if (!stream) {
          throw new Error('Failed to get download stream for image file');
        }
        formData.append('image[]', stream, {
          filename: imageFile.filename,
          contentType: imageFile.type,
        });
      }

      /** @type {import('axios').RawAxiosHeaders} */
      let headers = {
        ...formData.getHeaders(),
      };

      if (process.env.IMAGE_GEN_OAI_AZURE_API_VERSION && process.env.IMAGE_GEN_OAI_BASEURL) {
        headers['api-key'] = apiKey;
      } else {
        headers['Authorization'] = `Bearer ${apiKey}`;
      }

View on GitHub (pinned to 5ff282f900)

Solutions

1. Verify the object exists at imageFile.filepath in the underlying storage (e.g., `aws s3 ls` for S3, `ls` for local).
2. If the object is gone, delete the orphaned File metadata or re-upload the image.
3. Confirm storage credentials/permissions for the configured fileStrategy have read access.
4. For local storage, ensure the container/process has the data volume mounted and the path is accessible.
5. Add a preflight check that fetches file metadata and rejects missing objects with a user-facing message.

Example fix

// before — filepath points to a deleted S3 object
await imageEditTool.invoke({ prompt: '...', image_ids: ['file-x'] });
// 'Failed to get download stream for image file'

// after — preflight existence check (S3 example)
const { HeadObjectCommand, S3Client } = require('@aws-sdk/client-s3');
try {
  await s3.send(new HeadObjectCommand({ Bucket, Key: file.filepath }));
} catch {
  return 'That image is no longer available. Please re-upload it.';
}
await imageEditTool.invoke({ prompt: '...', image_ids: ['file-x'] });

async function assertFileReadable(file, fileStrategy) {
  const source = file.source || fileStrategy;
  const { getStrategyFunctions } = require('~/server/services/Files/strategies');
  const { getDownloadStream } = getStrategyFunctions(source);
  const stream = await getDownloadStream?.(req, file.filepath);
  if (!stream) throw new Error('Underlying object missing at ' + file.filepath);
  stream.destroy?.(); // release
}

function fileLooksStored(file) {
  return Boolean(file?.filepath && file?.source);
}

try {
  await imageEditTool.invoke(args);
} catch (e) {
  if (/Failed to get download stream/.test(e.message)) {
    return 'That image is no longer available; please re-upload it.';
  }
  throw e;
}

When it happens

Trigger: Editing an image where the stored `filepath` no longer points to an existing object — file deleted from disk/S3, the bucket object was removed out-of-band, the local file was pruned, the filepath is stale after a storage migration, or credentials lack read permission on the object.

Common situations: File record exists in Mongo but the underlying blob was deleted (orphaned metadata); local file cleared by a cleanup job; S3 lifecycle rule deleted the object; filepath stored with a wrong key after migration; expired/revoked storage credentials; container missing the mounted volume for local storage.

Related errors

• No download stream method found for source: ${source}
• No source found for image file
• This tool is only available for agents.
• Missing IMAGE_GEN_OAI_API_KEY environment variable.
• Missing required field: prompt

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