> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate and troubleshoot LibreChat

> Change the default model, rotate or revoke the gateway token, upgrade safely, remove the release, and fix common LibreChat errors on the TrueFoundry gateway.

This page covers the tasks after the first chat works: changing the default model, rotating and revoking access, upgrading, removing the release, and the errors you are most likely to see.

## Change the default model

Edit `models.default` in `librechat.yaml`, then upgrade the release with the same command you used to install it. Do not add `--reuse-values`, so the chart reads the new file:

```bash theme={"dark"}
helm upgrade librechat ~/charts/librechat-3.2.1.tgz \
  -n librechat \
  -f gw-values.yaml \
  --set-string librechat.existingSecretName=librechat-credentials-env \
  --set-file librechat.configYamlContent=librechat.yaml \
  --set ingress.enabled=false \
  --set meilisearch.enabled=false \
  --set-string librechat.configEnv.SCHEDULES_SINGLE_PROCESS=true \
  --timeout 8m
```

The new default must be a model that the virtual account has a grant for. Confirm it in the pod, as shown in [Install and verify](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#verify-the-gateway-path).

## Rotate the token

Rotate the token before it expires, or at once if you think it leaked. Turn on auto-rotation for production so the token renews before expiry and the owner is notified.

**1. Regenerate the token**

In **Access Management → Virtual Accounts**, open the account and regenerate its token. Copy the new token now. The console shows it once.

**2. Update the cluster secret**

Replace the value in place, without printing it:

```bash theme={"dark"}
read -rs TFY_TOKEN && echo
kubectl -n librechat create secret generic librechat-gateway-key \
  --from-literal=TFY_GATEWAY_KEY="$TFY_TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -
unset TFY_TOKEN
```

**3. Restart LibreChat**

The pod reads the token at start-up, so restart it:

```bash theme={"dark"}
kubectl -n librechat rollout restart deploy/librechat
kubectl -n librechat rollout status deploy/librechat --timeout=5m
```

Then repeat the completion check on a granted model. Expected: `200`.

Old tokens stop working as soon as you regenerate them. Restart LibreChat in the same window, or users see failed requests until the pod restarts.

## Revoke access

Both actions take effect at once at the gateway:

* To stop one model, open **Manage Permissions** on the virtual account and delete that grant. The trash icon removes it.
* To stop every call from LibreChat, delete the virtual account.

## Upgrade safely

The image store and MongoDB use `ReadWriteOnce` volumes. A rolling update can start a new pod that cannot attach a volume while the old pod still holds it. Scale the deployment to zero before the upgrade, then scale back up:

```bash theme={"dark"}
kubectl -n librechat scale deploy/librechat --replicas=0
helm upgrade librechat ~/charts/librechat-3.2.1.tgz -n librechat -f gw-values.yaml --timeout 8m
kubectl -n librechat scale deploy/librechat --replicas=1
```

Or use a storage class that supports `ReadWriteMany`.

## Remove the release

Uninstall the release, then delete the namespace:

```bash theme={"dark"}
helm uninstall librechat -n librechat
kubectl delete namespace librechat
```

Delete the virtual account too, in **Access Management → Virtual Accounts**, if you no longer need it.

A namespace can stay in `Terminating` after its resources are gone. A `kubernetes` finalizer blocks deletion when API discovery fails. Check the finalizers first:

```bash theme={"dark"}
kubectl get namespace librechat -o jsonpath='{.spec.finalizers}'
```

Clear the finalizer only after you confirm that the namespace holds nothing you need. Use the namespace finalize API:

```bash theme={"dark"}
kubectl get namespace librechat -o json | python3 -c "import sys,json; d=json.load(sys.stdin); d['spec']['finalizers']=[]; print(json.dumps(d))" \
  | kubectl replace --raw /api/v1/namespaces/librechat/finalize -f -
```

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Pod crash-loops with a `ZodError` on `endpoints.custom[0].models.default` | `models.fetch: true` without `models.default` | Add `models.default` with one provider-qualified model. See [librechat.yaml](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#librechat-yaml) |
| `403` on a model that appears in `/models` | The token has no grant for that model. `fetch` lists models the token cannot call | Grant the model in **Manage Permissions**. See [Grant a model](https://www.truefoundry.com/docs/ai-gateway/librechat/gateway-access.md#grant-a-model) |
| `403` on a bare model name such as `o4-mini` | The grant is on the provider-qualified ID | Use the full ID from the `/models` list, for example `azure-openai-main/o4-mini` |
| `400` with `not found in model account <provider>` | A bare name routed to a provider account that does not serve the model | Use the provider-qualified ID from the `/models` list |
| `400` with `Vertex: no access token` | The provider account has no credential | Set the credential on the provider account. This fix is in the provider account, not in LibreChat |
| `Illegal request` from a script | LibreChat rejects requests without a browser `User-Agent` | Send a browser-like `User-Agent` header from the script |
| `/api/health` returns `404` | This version has no `/api/health` endpoint | Use `/api/config` for a liveness check |
| `Registration is not allowed` | `ALLOW_REGISTRATION` is `false`, the default | Turn it on for an evaluation only. See [Sign in and send the first message](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#sign-in-and-send-the-first-message) |
| `FailedAttachVolume` during an upgrade | A `ReadWriteOnce` volume is still held by the old pod | Scale to zero, upgrade, then scale back up. See [Upgrade safely](#upgrade-safely) |
| `Request entity too large` on install or upgrade | The chart folder held a cache directory, so the release secret exceeded 3 MB | Package the chart from a clean copy with `helm package`. See [Build the chart](https://www.truefoundry.com/docs/ai-gateway/librechat/install-helm.md#build-the-chart) |
| A pod cannot reach another pod by IP | The chart's NetworkPolicy blocks probes by pod IP | Reach LibreChat through the service with `kubectl port-forward` |
| Namespace stuck in `Terminating` | A `kubernetes` finalizer, with API discovery failing | Clear the finalizer after you confirm the namespace is empty. See [Remove the release](#remove-the-release) |
| New chat shows **Unable to load this chat's model or agent** | No model is selected in the header | Select a model in the header, then send the message |

## Checklist

Use this list to confirm a working setup:

* [ ] Namespace `librechat` and secret `librechat-credentials-env` exist, with four keys
* [ ] Virtual account created, and its token stored in `librechat-gateway-key`
* [ ] At least one model granted with **Provider Integration Access**, and its provider-qualified ID noted
* [ ] `librechat.yaml` sets `models.default` to that ID
* [ ] Helm install finished, pods show `1/1 Running`, and volume claims show `Bound`
* [ ] Logs show `Connected to MongoDB` and the custom endpoint
* [ ] `/models` returns `200` and lists the granted ID
* [ ] A completion on the granted ID returns `200`
* [ ] A completion on a model you did not grant returns `403`
* [ ] Sign-in works, and a chat shows the granted model in the header badge


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.