Agent images frequently broken when using S3 CDN

[rmichela]

What happened?

I'm using the S3 CDN. When I upload an agent image, the generated signed S3 URL is broken in some parts of the UI.

Version Information

0.8.0-RC4

Steps to Reproduce

Config.yaml

fileStrategy: "s3"

Env Vars

AWS_REGION=us-east-1
AWS_BUCKET_NAME=librechat-cdn-bucket

1. Upload an agent image
2. Wait a little while
3. Reload the page

Expected: Agent images render in the model dropdown and the model chat.
Actual: Agent images are broken due to expired signed S3 image hrefs. Manually refreshing the page a few times fixes the issue for a short while.

What browsers are you seeing the problem on?

Chrome

Relevant log output

Broken S3 link

https://librechat-cdn-bucket.s3.us-east-1.amazonaws.com/images/68ed5ea215f7372617bcdf60/agent-agent_V3h3M4ZXXhXogyMSht_f7-avatar-1760536776704.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=[REDACTED]&X-Amz-Date=20251015T160408Z&X-Amz-Expires=120&X-Amz-Security-Token=[REDACTED]&X-Amz-Signature=fc873fe1137727886ca3ea62c19adc17c884bda5a14dbdb5ee1518723b0b7c5d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject


S3 response for the broken bucket

<Error>
   <Code>AccessDenied</Code>
   <Message>Request has expired</Message>
   <X-Amz-Expires>120</X-Amz-Expires>
   <Expires>2025-10-15T16:06:08Z</Expires>
   <ServerTime>2025-10-16T13:35:45Z</ServerTime>
   <RequestId>N7BXY5XZE0J71FT3</RequestId>
   <HostId>fEoCX+uGa1KteWLfCJnWqXyQos+BJvXrZ9QJiU2UrTY5ryJ9oM7l6DKkGyAYNfICzFNUytLLyBE=.</HostId>
</Error>

Screenshots

Code of Conduct

• I agree to follow this project's Code of Conduct

[georgenmatthew]

We also experienced this and have reverted back to using local storage.

It seems that the presigned S3 URLs expire and LibreChat does not consistently update/regenerate them.

I found that sometimes by modifying and re-saving an agent that LibreChat would regenerate the presigned URL.

[rmichela]

What's interesting is that the agent image in the agent editor always renders correctly.

When I inspected the S3 URLs of the agent image in the editor, it is different than the broken image links. Librechat can create updated image hrefs in some places.

[rmichela]

Repeatedly refreshing the browser temporarily fixes the problem.

[aron-muon]

You could set the env variable S3_URL_EXPIRY_SECONDS: "604800" # 1 week (this is the max amount of time allowed for pre-signed URLs)

But agreed there is something fundamentally wrong with how image URLs are refreshed.

[georgenmatthew]

Hi @rubentalstra , I was wondering if you may have any input on how we may be able to resolve this?

[danny-avila]

S3 presigned URLs are temporary access tokens, not designed for persistent static asset serving. The current refresh mechanism is a deliberate workaround for S3's security model, which has inherent limitations.

1. URL Generation: Images uploaded to S3 use presigned URLs with configurable expiry (S3_URL_EXPIRY_SECONDS, AWS max is 7 days, but without IAM access keys it's limited to just a few hours via STS tokens)

2. Refresh Logic: The codebase has refresh logic (refreshS3Url), but it's not applied everywhere, and we can observe a few of the patterns via agent queries:

   • Single agent GET (/agents/:id): Refreshes avatar URL before returning
   • List agents GET (/agents): Returns stored URLs without refreshing
   • Agent editor: Works because it uses the single agent endpoint

3. Why It Breaks: The model dropdown and chat UI use the list endpoint, which serves stale URLs. Only page reloads occasionally hit the single agent endpoint with refreshed URLs.

Many users expect 7-day expiry when setting S3_URL_EXPIRY_SECONDS, but if you're using temporary credentials (STS/IAM roles) instead of static IAM access keys, AWS limits presigned URLs to the credential lifetime (typically hours, not days). This compounds the issue.

Better Solutions:

1. CloudFront/CDN: The proper approach for static asset delivery. CloudFront with Origin Access Control eliminates presigned URLs entirely and provides true static serving.
2. Backend proxy endpoint: Serve images through an API endpoint that generates fresh presigned URLs on demand.

The second item was considered on first implementation but it increases load on the server, which defeats some of the purpose of leveraging an image service.

The current implementation was designed as a workaround for S3's security constraints, but for production use cases requiring persistent static assets, a proper CDN solution is more appropriate, rather trying to band-aid the current solution.

For the time being, I would not expect S3 to function like a proper CDN for images, like Firebase, which is more suitable for all file handling, and is already implemented. For an AWS solution to properly serve images without hacky workarounds, we are considering adding CloudFront.

Recommended Strategy

LibreChat supports granular file storage strategies via the fileStrategies config (instead of the single fileStrategy), which allows you to use different storage backends for different file types:

# In librechat.yaml
fileStrategies:
  avatar: "firebase"    # or "local" - avatars need persistent URLs
  image: "firebase"     # or "local" - images need persistent URLs
  document: "s3"        # documents are more appropriate for S3

I just realized fileStrategies still needs to be documented, so I will be working on that.

S3 is better suited for document storage (PDFs, text files, code files) where temporary presigned URLs for downloads make sense from a security perspective. For images that need to be displayed persistently across the UI, use Firebase or local storage, and we will consider CloudFront as an additional integration. This way, you can still leverage S3's benefits for document handling while avoiding the presigned URL expiration issues for visual assets.

[abhishekag03-cb]

@danny-avila when we use local for avatar, it does not work in case of multi instance deployments.
Is there a way to fix that?

[ethanlaj]

Can the backend proxy endpoint solution be reconsidered? Cloudfront isn't available in all AWS regions (specifically GovCloud) and ideally we want our images to be only available to logged in users

[vaibhav-Singh9888]

@danny-avila , totally agree presigned S3 URLs aren’t CDN-grade, and CloudFront / proxy / Firebase are the right long-term paths.
That said, there’s a concrete bug in the current workaround on List agents GET (/agents): the list endpoint does “refresh” only on cache-miss, but on cache-hit it returns the DB-stored (often expired) signed URL, because the cache was just a boolean (alreadyChecked=true). That’s why UI actions (model selector opens, etc.) can fetch within the cache window and get stale avatars, while an idle refetch after cache expiry looks fine.
I patched refreshListAvatars to cache the refreshed URLs (per-user map agentId -> filepath) and re-apply them on cache hits, instead of skipping refresh and returning Mongo’s stale URL. This keeps signing churn low while preventing the list endpoint from serving expired avatar URLs.

Shall i create an mr?

[danny-avila]

Thanks for the detailed assessment! Please do

[rmichela]

I'm also seeing similar behavior of expired S3 image links when rendering tool generated images in chat history. For example, images generated by OpenAI Image Tools. I'm starting to think that S3 isn't fit for purpose for CDN use.

[rmichela]

If I switch back to local for image hosting, how do I still support a multi-instance deployment on Amazon? EBS volumes won't work, because they can't be mounted by multiple pods. Perhaps replacing the local images mount with an EFS mount would work?

[georgenmatthew]

Yeah, we're using EFS for this after discovering the issues with S3.

[gshockbu]

What about using S3 Static Website hosting with a non-expiring link. We have been using that extensively for small static sites. Serving avatars that infrequently change seems like a perfect use case. You could make the URI a link in LC.YAML fileStategy: struct for S3. The service is nearly free !

[georgenmatthew]

Unfortunately this doesn't provide security in the case where you may not want the images publicly accessible.

[gshockbu]

Only for the Avatar which is public. That would be selectable in as

File storage strategy: Set to "s3" to use Amazon S3

fileStrategy: "s3"
avatar: s3://staticwwwsiteurl 

Other signed URL objects default to AWS_BUCKET_NAME:

[ethanlaj]

I don't want the avatar to be public

[gshockbu]

Anyone here using EFS as the alternative? Pros/Cons?

[abhishekag03-cb]

@danny-avila is there an ETA on this? It's a poor UX with broken icons.
We are unable to use local as we have multiple instances and even with a single instance it gets removed on redeploy.
s3 is not working for us either, images expire in one hour.

Please let us know if you have a solution to this? Hacky or permanent.