Docs
⚙️ Configuration
librechat.yaml
Settings
File Config

File Config Object Structure

Overview

The fileConfig object allows you to configure file handling settings for the application, including size limits and MIME type restrictions. This section provides a detailed breakdown of the fileConfig object structure.

There are 8 main fields under fileConfig:

  • endpoints
  • serverFileSizeLimit
  • avatarSizeLimit
  • imageGeneration
  • fileTokenLimit
  • ocr
  • text
  • stt

Notes:

  • At the time of writing, the Assistants endpoint supports filetypes from this list.
  • OpenAI, Azure OpenAI, Google, and Custom endpoints support files through the RAG API.
  • The ocr, text, and stt sections control file processing for features like Upload as Text and OCR
  • Any other endpoints not mentioned, like Plugins, do not support file uploads (yet).
  • The Assistants endpoint has a defined endpoint value of assistants. All other endpoints use the defined value default
    • For non-assistants endpoints, you can adjust file settings for all of them under default
    • If you’d like to adjust settings for a specific endpoint, you can list their corresponding endpoint names:
      • assistants
        • does not use “default” as it has defined defaults separate from the others.
      • openAI
      • azureOpenAI
      • google
      • YourCustomEndpointName
  • You can omit values, in which case, the app will use the default values as defined per endpoint type listed below.
  • LibreChat counts 1 megabyte as follows: 1 x 1024 x 1024

Example

fileConfig
fileConfig:
  endpoints:
    assistants:
      fileLimit: 5
      fileSizeLimit: 10
      totalSizeLimit: 50
      supportedMimeTypes:
        - "image/.*"
        - "application/pdf"
    openAI:
      disabled: true
    default:
      totalSizeLimit: 20
    YourCustomEndpointName:
      fileLimit: 5
      fileSizeLimit: 1000
      supportedMimeTypes:
        - "image/.*"
  serverFileSizeLimit: 1000
  avatarSizeLimit: 2
  fileTokenLimit: 100000
  imageGeneration:
    percentage: 100
    px: 1024
  ocr:
    supportedMimeTypes:
      - "^image/(jpeg|gif|png|webp|heic|heif)$"
      - "^application/pdf$"
      - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.presentation|spreadsheetml\\.sheet)$"
      - "^application/vnd\\.ms-(word|powerpoint|excel)$"
      - "^application/epub\\+zip$"
  text:
    supportedMimeTypes:
      - "^text/(plain|markdown|csv|json|xml|html|css|javascript|typescript|x-python|x-java|x-csharp|x-php|x-ruby|x-go|x-rust|x-kotlin|x-swift|x-scala|x-perl|x-lua|x-shell|x-sql|x-yaml|x-toml)$"
  stt:
    supportedMimeTypes:
      - "^audio/(mp3|mpeg|mpeg3|wav|wave|x-wav|ogg|vorbis|mp4|x-m4a|flac|x-flac|webm)$"

serverFileSizeLimit

KeyTypeDescriptionExample
serverFileSizeLimitIntegerThe global maximum size for any file uploaded to the server, specified in megabytes (MB).Acts as an overarching limit for file uploads across all endpoints, ensuring that no file exceeds this size server-wide.
fileConfig / serverFileSizeLimit
fileConfig:
  serverFileSizeLimit: 1000

avatarSizeLimit

KeyTypeDescriptionExample
avatarSizeLimitIntegerThe maximum size allowed for avatar images, specified in megabytes (MB).Specifically tailored for user avatar uploads, allowing for control over image sizes to maintain consistent quality and loading times.
fileConfig / avatarSizeLimit
fileConfig:
  avatarSizeLimit: 2

imageGeneration

KeyTypeDescriptionExample
imageGenerationObjectSettings related to image generation output quality and dimensions.Allows configuration of either output size as a percentage relative to some base size or as an explicit pixel dimension.

imageGeneration supports the following parameters:

  • percentage (Integer)

    • The output size of the generated image expressed as a percentage (e.g., 100 means 100% of base size).
    • Use this to scale the output image relative to a default or original size.

  • px (Integer)

    • Specifies the output image dimension in pixels (e.g., 1024).
    • Use this to explicitly set the output size of the generated image regardless of base size.

You may set only one of these parameters (percentage or px), not both, depending on your use case

Example configuration:

fileConfig / imageGeneration
fileConfig:
  imageGeneration:
    percentage: 100
    px: 1024

fileTokenLimit

KeyTypeDescriptionExample
fileTokenLimitNumberMaximum number of tokens from text files to include in prompts before truncation.fileTokenLimit: 100000

Description: When attaching text content, LibreChat truncates the text at runtime to the configured token limit just before prompt construction.

Default: 100000

fileConfig / fileTokenLimit
fileConfig:
  fileTokenLimit: 100000

ocr

KeyTypeDescriptionExample
ocrObjectSettings for Optical Character Recognition (OCR) file processing.Configures which file types are processed using OCR.

Description: The ocr section configures which file types should be processed using OCR functionality for extracting text from visual documents.

Note: This section controls file type matching for OCR processing. To enable agent capabilities and configure OCR services, see:

supportedMimeTypes

KeyTypeDescriptionExample
supportedMimeTypesArray of StringsList of MIME type patterns for files that should be processed with OCR.Uses regular expressions to match file types.

Default: Images, PDFs, and Office documents

fileConfig / ocr / supportedMimeTypes
fileConfig:
  ocr:
    supportedMimeTypes:
      - "^image/(jpeg|gif|png|webp|heic|heif)$"
      - "^application/pdf$"
      - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.presentation|spreadsheetml\\.sheet)$"
      - "^application/vnd\\.ms-(word|powerpoint|excel)$"
      - "^application/epub\\+zip$"

text

KeyTypeDescriptionExample
textObjectSettings for direct text file parsing without OCR.Configures which file types are processed as plain text files for direct content extraction.

Description: The text section configures which file types should be processed using direct text extraction.

Note: Text parsing is the default method used by the “Upload as Text” feature (controlled by the context capability). It first attempts to use the text parsing library from the RAG API, and if the RAG API is not connected, it falls back to a simpler text extraction method without requiring any external services. See Upload as Text for more information.

supportedMimeTypes

KeyTypeDescriptionExample
supportedMimeTypesArray of StringsList of MIME type patterns for files that should be parsed as plain text.Uses regular expressions to match file types.

Default: All text files and common programming languages

fileConfig / text / supportedMimeTypes
fileConfig:
  text:
    supportedMimeTypes:
      - "^text/(plain|markdown|csv|json|xml|html|css|javascript|typescript|x-python|x-java|x-csharp|x-php|x-ruby|x-go|x-rust|x-kotlin|x-swift|x-scala|x-perl|x-lua|x-shell|x-sql|x-yaml|x-toml)$"

stt

KeyTypeDescriptionExample
sttObjectSettings for Speech-to-Text (STT) audio file processing.Configures which audio file types are processed using STT for transcription.

Description: The stt section configures which audio file types should be processed using Speech-to-Text functionality for converting audio to text.

supportedMimeTypes

KeyTypeDescriptionExample
supportedMimeTypesArray of StringsList of MIME type patterns for audio files that should be transcribed with STT.Uses regular expressions to match audio file types.

Default: Common audio formats

fileConfig / stt / supportedMimeTypes
fileConfig:
  stt:
    supportedMimeTypes:
      - "^audio/(mp3|mpeg|mpeg3|wav|wave|x-wav|ogg|vorbis|mp4|x-m4a|flac|x-flac|webm)$"

Notes:

  • Files matching text patterns are processed with simple text extraction
  • Files matching ocr patterns are processed with the provided OCR service
  • Files matching stt patterns are processed with Speech-to-Text transcription
  • Processing precedence: OCR > STT > text parsing > fallback
  • Files not matching any pattern will fall back to text parsing

File Processing Priority

LibreChat processes uploaded files based on MIME type matching with the following priority order:

  1. OCR - If file matches ocr.supportedMimeTypes AND OCR is configured
  2. STT - If file matches stt.supportedMimeTypes AND STT is configured
  3. Text Parsing - If file matches text.supportedMimeTypes
  4. Fallback - Text parsing as last resort

This processing order ensures optimal extraction quality while maintaining functionality even when specialized services (OCR/STT) are not configured.

Processing Examples

PDF file with OCR configured:

  • File matches ocr.supportedMimeTypes
  • Uses OCR to extract text
  • Better quality for scanned PDFs and images

PDF file without OCR configured:

  • File matches text.supportedMimeTypes (or uses fallback)
  • Uses text parsing library
  • Works well for digital PDFs with selectable text

Python file:

  • File matches text.supportedMimeTypes
  • Uses text parsing (no OCR needed)
  • Direct text extraction

Audio file with STT configured:

  • File matches stt.supportedMimeTypes
  • Uses STT to transcribe audio to text

Image file without OCR configured:

  • File matches ocr.supportedMimeTypes but OCR not available
  • Falls back to text parsing
  • Limited extraction capability without OCR

This priority system allows features like “Upload as Text” to work without requiring OCR configuration, while still leveraging OCR when available for improved extraction quality.

endpoints

KeyTypeDescriptionExample
endpointsRecord/ObjectConfigures file handling settings for individual endpoints, allowing customization per endpoint basis.Specifies file handling configurations for individual endpoints, allowing customization per endpoint basis.

Description: Each object under endpoints is a record that can have the following settings:

Overview

  • disabled
    • Whether file handling is disabled for the endpoint.
  • fileLimit
    • The maximum number of files allowed per upload request.
  • fileSizeLimit
    • The maximum size for a single file. In units of MB (e.g. use 20 for 20 megabytes)
  • totalSizeLimit
    • The total maximum size for all files in a single request. In units of MB (e.g. use 20 for 20 megabytes)
  • supportedMimeTypes
    • A list of Regular Expressions specifying what MIME types are allowed for upload. This can be customized to restrict file types.

disabled

KeyTypeDescriptionExample
disabledBooleanIndicates whether file uploading is disabled for a specific endpoint.Setting this to `true` prevents any file uploads to the specified endpoint, overriding any other file-related settings.

Default: false

fileConfig / endpoints / {endpoint_record} / disabled
openAI:
  disabled: true

fileLimit

Key:

KeyTypeDescriptionExample
fileLimitIntegerThe maximum number of files allowed in a single upload request.Helps control the volume of uploads and manage server load.

Default: Varies by endpoint

fileConfig / endpoints / {endpoint_record} / fileLimit
assistants:
  fileLimit: 5

fileSizeLimit

Key:

KeyTypeDescriptionExample
fileSizeLimitIntegerThe maximum size allowed for each individual file, specified in megabytes (MB).This limit ensures that no single file exceeds the specified size, allowing for better resource allocation and management.

Default: Varies by endpoint

fileConfig / endpoints / {endpoint_record} / fileSizeLimit
YourCustomEndpointName:
  fileSizeLimit: 1000

totalSizeLimit

Key:

KeyTypeDescriptionExample
totalSizeLimitIntegerThe total maximum size allowed for all files in a single request, specified in megabytes (MB).This setting is crucial for preventing excessive bandwidth and storage usage by any single upload request.

Default: Varies by endpoint

fileConfig / endpoints / {endpoint_record} / totalSizeLimit
assistants:
  totalSizeLimit: 50

supportedMimeTypes

Key:

KeyTypeDescriptionExample
supportedMimeTypesArray of StringsA list of regular expressions defining the MIME types permitted for upload.This allows for precise control over the types of files that can be uploaded. Invalid regex is ignored.

Default: Varies by endpoint

fileConfig / endpoints / {endpoint_record} / supportedMimeTypes
assistants:
  supportedMimeTypes:
      - "image/.*"
      - "application/pdf"
RegistrationTransactions