ZoneInfoNotFoundError: No time zone found with key ‘Asia/Taipei’ when using APScheduler on Windows

by

Summary

When deploying a FastAPI application with APScheduler 3.10 on Windows, passing the timezone "Asia/Taipei" raises a ZoneInfoNotFoundError. This issue does not occur on Linux/macOS systems, where timezone data is typically pre-installed. Despite attempts to resolve it by installing the tzdata package and setting the TZDIR environment variable, the error persists due to platform-specific timezone handling in Python’s standard library.

Root Cause

The error stems from two primary factors:

  • Python’s zoneinfo module relies on system-level timezone data, which is incomplete or outdated on Windows compared to Unix-like systems.
  • APScheduler 3.10+ uses zoneinfo for timezone resolution, but Windows lacks the necessary IANA timezone database entries without explicit configuration.

Installing tzdata alone is insufficient on Windows because:

  • The zoneinfo module requires TZDIR to point to the correct data directory.
  • Windows does not automatically include the required timezone definitions, even with tzdata installed.

Why This Happens in Real Systems

Key reasons include:

  • Platform-dependent timezone data availability:
    • Linux/macOS systems have access to the IANA timezone database by default.
    • Windows requires manual installation and configuration of timezone data.
  • Dependency version drift: APScheduler 3.10’s shift to zoneinfo (from pytz) exposes reliance on system data.
  • Incomplete environment setup: Developers often overlook Windows-specific timezone configuration in development environments.

Real-World Impact

  • Application failures in production: Scheduled jobs for critical regions like Asia/Taipei fail silently or crash.
  • Inconsistent behavior across environments: Code that works locally on macOS/Linux breaks when deployed on Windows servers.
  • Operational overhead: Teams waste time debugging platform-specific issues instead of focusing on core features.

Example or Code

# Original failing code
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.cron import CronTrigger

scheduler = BackgroundScheduler(timezone="Asia/Taipei")
scheduler.add_job(my_job, CronTrigger(hour=8, minute=0, timezone="Asia/Taipei"))
scheduler.start()

How Senior Engineers Fix It

Senior engineers take a proactive, cross-platform approach:

  • Explicitly install and configure timezone data on Windows:
    • Use pip install tzdata to include the IANA database.
    • Set the TZDIR environment variable to the tzdata package’s data directory.
  • Implement fallback logic:
    • Validate timezone availability before scheduler initialization.
    • Use a default timezone (e.g., UTC) if the target timezone is missing.
  • Containerize or standardize environments:
    • Ensure Docker containers or deployment scripts include the required timezone data.

Why Juniors Miss It

Common pitfalls include:

  • Assuming cross-platform consistency: Juniors often develop on macOS/Linux and assume Windows behaves identically.
  • Skipping platform-specific testing: They may not test timezones on Windows during development.
  • Misunderstanding dependency chains: Overlooking that tzdata requires additional configuration on Windows to override system defaults.
  • Ignoring error logs: Missing the ZoneInfoNotFoundError as a hint to investigate timezone data availability.

Leave a Comment