Troubleshooting¶
Common problems with the LiteLLM Proxy gateway, what causes them and how to fix them.
HTTP 500 when no key is sent¶
Cause: LiteLLM 1.104.2 answers a request with no Authorization header
with HTTP 500 instead of 401. The request is still refused.
Fix: send Authorization: Bearer <master key>.
HTTP 400, 401 or 403 with a key¶
Cause: the key does not match /var/lib/litellm-proxy/master.key, often
after a rotation.
Fix: use the current master key in your client.
Certificate verification fails¶
Cause: the certificate is self-signed, so your client does not trust it by
default, or you reached the gateway by a name other than localhost or
127.0.0.1.
Fix: give your client a copy of /var/lib/litellm-proxy/tls/cert.pem and
connect through localhost with port forwarding. Do not turn verification
off.
Connection refused from another host¶
Cause: the proxy listens on 127.0.0.1 only.
Fix: use Session Manager port forwarding, or a reverse proxy on the instance, see Reach the gateway from other machines.
Provider key lost after a reboot¶
Cause: the key was added to /etc/litellm-proxy/runtime.env, which first
boot rewrites on every boot.
Fix: move it to a separate environment file loaded by a drop-in, see Add a provider.
A new model returns an error¶
Cause: the provider key is missing from the service environment, the
model string is wrong, or the instance cannot reach the provider over
outbound HTTPS.
Fix: check the proxy log for the provider's error message, confirm the drop-in is loaded, and check the security group and network path:
The proxy does not start after a config change¶
Cause: config.yaml is not valid YAML, or a setting is not accepted.
Fix: read the error, correct the file and restart:
First boot fails¶
Cause: an identity file is a symbolic link, not a regular file, or has
hard links, or the master key is malformed (it must start with sk-). First
boot refuses to use such files.
Fix: read the reason, replace the file with a regular one or remove it to have it recreated, then retry:
sudo journalctl -u sushi-litellm-proxy-firstboot --no-pager
sudo systemctl restart sushi-litellm-proxy-firstboot
sudo systemctl start litellm-proxy
If it still fails, contact info@softwaresushi.com.
Last updated October 13, 2026 · Suggest an improvement