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.

The main fields under fileConfig covered here:

• endpoints
• skills
• serverFileSizeLimit
• avatarSizeLimit
• imageGeneration
• clientImageResize
• fileTokenLimit
• fileContextSizeLimit
• fileContextCharLimit
• defaultLLMDeliveryPath
• legacyFileUploadUX
• textFallbackWithoutTools
• codeEnvLivenessSafeWindowMs
• legacySearchProbeTimeoutMs
• ocr
• text

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.
• OpenAI, Azure OpenAI, Anthropic, Google, AWS Bedrock, and custom endpoints support direct file uploads via Upload to Provider.
• The ocr and text 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
    • bedrock
    • 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
• Long-running upload response streaming and server-side remote URL fetch limits are configured with the FILE_UPLOAD_SSE_ENABLED, REMOTE_FILE_FETCH_TIMEOUT_MS, and REMOTE_FILE_FETCH_MAX_BYTES environment variables.

Example

fileConfig:
  endpoints:
    assistants:
      fileLimit: 5
      fileSizeLimit: 10
      totalSizeLimit: 50
      supportedMimeTypes:
        - "image/.*"
        - "application/pdf"
    openAI:
      disabled: true
    default:
      totalSizeLimit: 20
      defaultLLMDeliveryPath:
        fallback: text
        overrides:
          "image/*": provider
    YourCustomEndpointName:
      fileLimit: 5
      fileSizeLimit: 1000
      supportedMimeTypes:
        - "image/.*"
  serverFileSizeLimit: 1000
  avatarSizeLimit: 2
  fileTokenLimit: 100000
  skills:
    fileSizeLimit: 50
  fileContextSizeLimit: 128
  fileContextCharLimit: 1000000
  legacyFileUploadUX: false
  imageGeneration:
    percentage: 100
  clientImageResize:
    maxWidth: 1900
    maxHeight: 1900
    quality: 0.92
  ocr:
    supportedMimeTypes:
      - "^image/(jpeg|gif|png|webp|heic|heif)$"
      - "^application/pdf$"
      - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.(presentation|template)|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)$"

skills

skills supports three parameters:

• fileSizeLimit (Number)
  • Maximum size of a single Skill upload, specified in megabytes (MB).
  • Default: 50
• importCleanupConcurrency (Integer)
  • Maximum concurrent cleanup operations after a failed Skill archive import. Use 1 for serial cleanup.
  • Default: 8
• deletionCleanupConcurrency (Integer)
  • Maximum concurrent cleanup operations when a Skill is deleted. Use 1 for serial cleanup.
  • Default: 8

fileConfig:
  skills:
    fileSizeLimit: 50
    importCleanupConcurrency: 8
    deletionCleanupConcurrency: 8

See Skills for the rest of the import rules, such as the per-file and archive-entry limits.

serverFileSizeLimit

fileConfig:
  serverFileSizeLimit: 1000

avatarSizeLimit

fileConfig:
  avatarSizeLimit: 2

imageGeneration

imageGeneration supports the following parameters:

• percentage (Number)

  • 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 (Number)

  • 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.

Set only one of these parameters (percentage or px), not both.

Example configuration:

fileConfig:
  imageGeneration:
    percentage: 100

clientImageResize

Controls client-side resizing of images before upload, which prevents upload errors from oversized images. Users can toggle resizing in Settings > Chat. Setting enabled here overrides that choice for everyone and locks the toggle; omit it to leave users in control.

• enabled (Boolean)
  • Force resizing on (true) or off (false) for everyone. When omitted, each user decides, with resizing on by default.
• maxWidth (Number)
  • Maximum width of resized images, in pixels. Minimum 1. Default: 1900
• maxHeight (Number)
  • Maximum height of resized images, in pixels. Minimum 1. Default: 1900
• quality (Number)
  • JPEG compression quality from 0 to 1. Default: 0.92

fileConfig:
  clientImageResize:
    enabled: true
    maxWidth: 1900
    maxHeight: 1900
    quality: 0.92

fileTokenLimit

Description: When attaching text content, LibreChat truncates the text at runtime to the configured token limit just before prompt construction. The limit applies to each file separately. Users can override it for a conversation with the File Token Limit model parameter. Setting it to 0 stops attached file text from being added to the prompt at all.

Default: 100000

fileConfig:
  fileTokenLimit: 100000

fileContextSizeLimit

Default: 128 MB. This is a per-turn prompt-safety ceiling, separate from upload storage limits. Embedded File Search resources, Code workspace references, and files that do not enter model context are excluded. A configured endpoint totalSizeLimit can impose a lower aggregate byte limit for that endpoint.

fileConfig:
  fileContextSizeLimit: 128

fileContextCharLimit

Default: 1000000. LibreChat applies this bound to extracted text entering the Agent prompt, including retained conversation attachments and Agent-scoped File Context. Repeated injections are counted for each Agent that receives them. Exceeding either context limit stops the turn with an attachment-limit error before the model is invoked.

fileConfig:
  fileContextCharLimit: 1000000

textFallbackWithoutTools

When an upload is routed to none (stored, available only to tools) and the turn runs no tool that can read it, LibreChat can deliver the file's extracted text instead. Set textFallbackWithoutTools: true to enable this. It can be set globally under fileConfig, or per entry under fileConfig.endpoints (including default); an endpoint value takes precedence over the global one.

Default: false

It applies only to message attachments whose route was inferred; a destination the user chose explicitly is never re-resolved, and files kept on an agent's tool resources never reach a prompt. Only the built-in document and plain-text extractors run, so no RAG or OCR call is made for a file meant for a tool. Existing files without extracted text are not backfilled.

fileConfig:
  textFallbackWithoutTools: true
  endpoints:
    openAI:
      textFallbackWithoutTools: false

codeEnvLivenessSafeWindowMs

Files provisioned to the code execution environment within this window (in milliseconds) skip the live availability check before reuse. Minimum 0.

Default: 21600000 (6 hours)

fileConfig:
  codeEnvLivenessSafeWindowMs: 21600000

legacySearchProbeTimeoutMs

How long, in milliseconds, priming waits on a legacy File Search availability check before embedding the file anyway. Minimum 1.

Default: 5000

fileConfig:
  legacySearchProbeTimeoutMs: 5000

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:

• Agents Configuration for the ocr and context capabilities
• OCR Configuration for OCR service setup

supportedMimeTypes

Default: Images, PDFs, and Office documents

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

text

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). See Upload as Text for more information.

• The default list matches any well-formed MIME type. Files that are already text (text/*, JSON, YAML, XML, SQL, shell scripts, .eml email and similar) are read directly. Other binary types without a parser are rejected rather than decoded into garbage.
• If you narrow the list and the RAG API is configured (RAG_API_URL), files matching it are sent to the RAG API's text extraction. If the RAG API is unavailable, LibreChat falls back to its built-in document parser.

supportedMimeTypes

Default: ^[\w.-]+/[\w.-]+$ (any MIME type)

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

fileConfig.stt is not read in current versions of LibreChat; an stt block here is ignored. Audio files added as text are transcribed when a speech-to-text provider is configured under speech.stt, using a built-in list of audio types: MP3, MPEG, WAV, OGG, Vorbis, MP4 and M4A audio, FLAC, WebM, AAC, WMA, and Opus.

File Processing Priority

When a file is added as text (Upload as Text, a long paste, or agent File Context), LibreChat uses the first step that applies:

1. OCR: an ocr section exists in librechat.yaml and the file matches fileConfig.ocr.supportedMimeTypes. If the OCR service fails, the built-in document parser is tried next.
2. RAG API text extraction: text.supportedMimeTypes has been narrowed from the default, the RAG API is configured, and the file matches the list.
3. Built-in document parser: PDF, DOCX, XLS and XLSX, ODT, and ODS files. It reads text layers only.
4. Speech-to-text: audio files, when an STT provider is configured.
5. Text parsing: files matching text.supportedMimeTypes.

An image or a scanned PDF with no OCR configured has no extractable text and the upload fails with a message that an OCR service is needed.

legacyFileUploadUX

Description: By default, the attach menu offers From Local Computer and LibreChat decides per file how the model receives it, following defaultLLMDeliveryPath. File Search and Code resources are provisioned only when a selected tool needs the file. With legacyFileUploadUX: true, users choose the destination themselves, uploads go to that destination right away, and the explicit Upload as Text option appears. A per-endpoint value overrides the top-level one.

fileConfig:
  legacyFileUploadUX: true
  endpoints:
    anthropic:
      legacyFileUploadUX: false

defaultLLMDeliveryPath

Each value is one of:

• provider: the file is sent to the model as a native attachment (image, PDF, audio, or video input).
• text: the file's text is extracted and added to the prompt, as with Upload as Text.
• none: the file is stored and available to tools such as code execution or file search, but not sent to the model.

overrides maps a MIME type, or a type/* wildcard, to a value. fallback applies to everything not listed. LibreChat checks endpoint overrides, then the endpoint fallback, then top-level overrides, then the top-level fallback, then the built-in default.

The built-in default sends images, audio, video, and PDFs to the provider and everything else as text. It also adjusts for the endpoint: a PDF on a provider that cannot read PDFs is sent as text, audio or video on a provider without media support is transcribed or kept off the prompt, AWS Bedrock receives its supported document types natively, and types with no way to extract text (archives, for example) are set to none. Values you configure are used as written, without these adjustments.

fileConfig:
  defaultLLMDeliveryPath:
    fallback: text
    overrides:
      'image/*': provider
      'video/*': none
  endpoints:
    openAI:
      defaultLLMDeliveryPath:
        overrides:
          application/pdf: provider

endpoints

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)
• defaultLLMDeliveryPath, legacyFileUploadUX, and textFallbackWithoutTools
  • Per-endpoint overrides of the global settings of the same name described above.
• supportedMimeTypes
  • A list of Regular Expressions specifying what MIME types are allowed for upload. This can be customized to restrict file types.

disabled

Default: false

openAI:
  disabled: true

fileLimit

Key:

Default: Varies by endpoint

assistants:
  fileLimit: 5

fileSizeLimit

Key:

Default: Varies by endpoint

YourCustomEndpointName:
  fileSizeLimit: 1000

totalSizeLimit

Key:

Default: Varies by endpoint

assistants:
  totalSizeLimit: 50

supportedMimeTypes

Key:

Default: Varies by endpoint

assistants:
  supportedMimeTypes:
      - "image/.*"
      - "application/pdf"

LibreChat normalizes common MIME aliases before applying these patterns. In particular, application/x-shellscript (reported by Chrome on Linux) and text/x-shellscript (reported by libmagic) become application/x-sh. A custom allowlist that accepts shell scripts should therefore permit the canonical application/x-sh type. Rejected uploads return the reported unsupported type to the client instead of a generic server error.

Retained File and Vector Cleanup

File deletion preserves the readable primary until secondary storage cleanup is confirmed. fileConfig.retainedFileCleanup defaults to false: embedded files and retained Code Interpreter destinations are not destructively cleaned up until it is explicitly enabled. Enable it only after every replica and rollback target reads retained file destinations.

Vector deletion additionally requires complete recorded ownership and insert-time proof at or after the safe writer cutoff. Missing, invalid, future, or pre-cutoff proof fails closed and leaves the file and its vectors in place. Setting the cutoff does not repair older ownership metadata, and it must not be backdated to make ambiguous legacy files eligible.

Cleanup targets each recorded entity namespace and the unscoped namespace. A namespace is accepted as cleaned after a successful DELETE response. A 404 is accepted as absence only after a successful same-namespace inventory check excludes the file. If any secondary or namespace cannot be confirmed absent, the primary remains available for retry. These settings do not backfill legacy records; plan a separately verified reconciliation for ambiguous historical files.