503 HTTP Response on OpenID Authentication when running multiple instances of API

[STeveShary]

What happened?

This is an interesting bug that I found when integrated with OpenID. I found that when I tested locally, everything worked great, but then in our test environment, I would see HTTP 503 responses when handling the callback.

This is a "transient" bug in the fact that if your load balancer sends you to a different instance in the callback from the originating instance, you will see this bug. If the originating instance and the callback instance are the same, you won't see this bug.

Version Information

Git Commit hash -> 6dd1b3988651ea4b56b2b84d9ae8e042fbdd0bc1

This bug was found using the packaged docker instance -> librechat/librechat:v0.7.8

Setup to reproduce locally

In your docker-compose.yml:

1. add the following to the services -> api

    deploy:
      replicas: 3

2. Change your api -> ports setting from "${PORT}:${PORT}" to "${PORT}"
3. Add the following section to the services for a load balancer:

  loadbalancer:
    image: nginx:latest
    container_name: chat-nginx
    ports:
      - 3080:3080
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - api

Create a nginx.conf file with the contents:

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 3080;
        
        access_log /var/log/nginx/access.log;
        error_log /var/log/nginx/error.log;

        location / {
            proxy_pass http://api:3080;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

Lastly, you should setup an OpenID authentication according to the documentation -> https://www.librechat.ai/docs/configuration/authentication/OAuth2-OIDC

At this point, you can follow the steps to reproduce below.

Steps to Reproduce

1. With the local setup described above, start the suite of apps with docker compose up
2. Navigate to http://localhost:3080
3. Begin the login with the OpenID process.
4. (You will be navigated back to the /oauth/openid/callback or whatever you have set on the OPENID_CALLBACK_URL environment variable.)

Expected Action

Your authentication is completed and you arrrive at the /c/new page.

Actual Response

You get the page with Internal Server Error on the /oauth/openid/callback page (with the code and state query params).

Workarounds

There are several work arounds:

1. Ask users to refresh the callback page (the Internal Server Error) until the authentication hits the originating instance and the login completes (not ideal).
2. Setup the load balancer to use "sticky sessions" where a client session is "pinned" to a instance of the API. (More info available here -> https://traefik.io/glossary/what-are-sticky-sessions/)
3. Run exactly one instance of the API.

What browsers are you seeing the problem on?

No response

Relevant log output

Below are the logs from the steps to reproduce with the load balancer setup.
----------------------------------------------------------------------------

chat-nginx    | 192.168.65.1 - - [19/May/2025:14:46:15 +0000] "GET /login HTTP/1.1" 200 1102 "http://localhost:3080/login" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
api-1         | {"level":"debug","message":"X-Forwarded headers detected in OAuth request:","timestamp":"2025-05-19T14:46:16.699Z","x-forwarded-for":"192.168.65.1","x-forwarded-proto":"http"}
chat-nginx    | 192.168.65.1 - - [19/May/2025:14:46:16 +0000] "GET /oauth/openid HTTP/1.1" 302 0 "http://localhost:3080/login" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
chat-nginx    | 192.168.65.1 - - [19/May/2025:14:46:17 +0000] "GET /sw.js HTTP/1.1" 304 0 "http://localhost:3080/sw.js" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
f,"timestamp":"2025-05-19T14:46:17.376Z","x-forwarded-for":"192.168.65.1","x-forwarded-proto":"http"}
chat-nginx    | 192.168.65.1 - - [19/May/2025:14:46:17 +0000] "GET /oauth/openid/callback?code=XXXX&state=XXX HTTP/1.1" 500 148 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
api-2         | Error: did not find expected authorization request details in session, req.session["oidc:xxx.okta.com"] is undefined
api-2         |     at /app/node_modules/openid-client/lib/passport_strategy.js:132:13
api-2         |     at OpenIDConnectStrategy.authenticate (/app/node_modules/openid-client/lib/passport_strategy.js:191:5)
api-2         |     at attempt (/app/node_modules/passport/lib/middleware/authenticate.js:369:16)
api-2         |     at authenticate (/app/node_modules/passport/lib/middleware/authenticate.js:370:7)
api-2         |     at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5)
api-2         |     at next (/app/node_modules/express/lib/router/route.js:149:13)
api-2         |     at Route.dispatch (/app/node_modules/express/lib/router/route.js:119:3)
api-2         |     at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5)
api-2         |     at /app/node_modules/express/lib/router/index.js:284:15
api-2         |     at Function.process_params (/app/node_modules/express/lib/router/index.js:346:12)

Screenshots

No response

Code of Conduct

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

[danny-avila]

This is not a bug in the LibreChat codebase itself, but rather an expected behavior when using session-based authentication in a distributed environment without proper session management.

What you're experiencing is a common challenge in horizontally scaled applications:

1. The first request creates an authentication session on instance A
2. The load balancer routes the callback to instance B
3. Instance B doesn't have access to the session data created on instance A

This is a fundamental architectural consideration rather than a code defect. In distributed systems with stateful authentication flows, you need one of the following:

1. Sticky sessions (as you've noted in workarounds)
2. Distributed session storage (Redis, etc.)
3. Stateless authentication where possible

The LibreChat application includes Redis for session storage, which should be properly configured in production environments with multiple instances. The default Docker setup uses in-memory session storage which works correctly for single-instance deployments.

I recommend configuring Redis session storage for your multi-instance deployment as documented here: LibreChat Redis Configuration

[STeveShary]

@danny-avila Thanks for the quick reply. Do you think it would be helpful to provide this in the documentation? I'd be happy to help write it!