[Bug]: Proxy exits at startup when TZ is Asia/Calcutta on a pip install, tzdata isn’t installed

问题场景

用户通过 pip 安装 litellm[proxy]，在全新 venv 中执行 TZ=Asia/Calcutta LITELLM_MASTER_KEY=sk-test litellm --config config.yaml --port 4000 启动 LiteLLM Proxy。主机为 Ubuntu 26.04（WSL）、Python 3.14，未安装 tzdata-legacy。启动过程中调度器向 tzlocal 查询本地时区时无法解析 Asia/Calcutta，进程以退出码 3 结束。虽然 Asia/Calcutta 是指向 Asia/Kolkata 的合法 IANA 别名，但该旧别名已从 Ubuntu 24.04+ 的默认 tz 数据库中移出。

报错原文

ZoneInfoNotFoundError: 'tzlocal() does not support non-zoneinfo timezones like Asia/Calcutta. Please use a timezone in the form of Continent/City'

原因分析

最可能的原因是依赖链中的时区数据缺失。proxy extra 会引入 apscheduler，其通过 tzlocal 解析本地时区；当主机缺少旧版时区别名文件、且 pip 环境里也没有提供兜底数据的 tzdata 包时，Asia/Calcutta 无法被解析，导致启动中断。Docker 镜像此前已通过 #8915 安装了 tzdata，因此不受影响，而 pip 安装方式没有对应的依赖声明。Issue 中提到 #8657 曾报告过同一 pip 安装场景下的失败，但被标记为 stale 关闭。

环境排查

• 确认 LiteLLM 安装方式：是否为 pip 安装的 litellm[proxy]，以及具体版本（Issue 报告为 v1.105.1）。
• 确认 Python 版本与虚拟环境：Issue 环境为 Python 3.14 的全新 venv。
• 确认操作系统及其时区包：Ubuntu 24.04+ 是否安装 tzdata-legacy；WSL 环境下注意确认使用的是 WSL 发行版自身的时区数据。
• 确认当前环境是否已安装 tzdata（pip install tzdata 是否已执行过）。
• 确认 TZ 环境变量的取值：Asia/Calcutta 属于旧别名，可考虑改用 Asia/Kolkata（Issue 未验证该写法，属于可优先尝试的规避方式）。

解决步骤

1. 在启动 proxy 的同一虚拟环境中执行 pip install tzdata，为 Python zoneinfo 提供时区兜底数据。
2. 保持原有启动命令不变，重新执行 TZ=Asia/Calcutta LITELLM_MASTER_KEY=sk-test litellm --config config.yaml --port 4000。
3. 若仍希望从系统层面解决，可安装 Ubuntu 的 tzdata-legacy 包以恢复旧时区别名（Issue 只提到该包的存在，未给出具体安装命令，请按发行版文档操作）。
4. 后续升级 LiteLLM 时，确认所用版本是否已将 tzdata 纳入 proxy extra；若已纳入，可不再手动安装。

验证方法

重新启动后，启动日志应出现 “Application startup complete”，且进程不再因 ZoneInfoNotFoundError 以退出码 3 结束；可再请求 /health 等端点，确认 proxy 已正常监听。

参考来源

BerriAI/litellm #49813；关联修复 PR：#49914；Docker 镜像相关：#8915；历史报告：#8657。

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。