{"record":{"id":"27a885a06e3cb3e3","repo":"HKUDS/Vibe-Trading","slug":"timezone-tz-r-is-not-a-recognized-iana-timezone","errorCode":null,"errorMessage":"timezone {tz!r} is not a recognized IANA timezone key","messagePattern":"timezone (.+?) is not a recognized IANA timezone key","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"agent/src/scheduled_research/models.py","lineNumber":176,"sourceCode":"    \"\"\"Raise ``ValueError`` when *tz* is not a resolvable IANA timezone key.\n\n    ``None`` is always valid and means legacy UTC semantics. Resolution goes\n    through :class:`zoneinfo.ZoneInfo`, so whatever validates here is exactly\n    what the executor can evaluate later.\n\n    Args:\n        tz: An IANA timezone key such as ``\"Pacific/Auckland\"``, or ``None``.\n\n    Raises:\n        ValueError: When *tz* is not ``None`` and cannot be resolved.\n    \"\"\"\n    validate_timezone_shape(tz)\n    if tz is None:\n        return\n    try:\n        ZoneInfo(tz)\n    except Exception as exc:\n        raise ValueError(f\"timezone {tz!r} is not a recognized IANA timezone key\") from exc\n\n\n# ---------------------------------------------------------------------------\n# Status enum\n# ---------------------------------------------------------------------------\n\n\nclass JobStatus(str, Enum):\n    \"\"\"Lifecycle status of a scheduled research job.\"\"\"\n\n    PENDING = \"pending\"\n    RUNNING = \"running\"\n    COMPLETED = \"completed\"\n    FAILED = \"failed\"\n    CANCELLED = \"cancelled\"\n    EXPIRED = \"expired\"\n\n","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/scheduled_research/models.py#L158-L194","documentation":"Raised by validate_timezone in agent/src/scheduled_research/models.py:176 when a non-None timezone string cannot be constructed into a ZoneInfo, i.e. it is not a recognized IANA timezone database key. The library validates timezones eagerly so scheduled jobs always have a computable local time. It wraps the underlying ZoneInfoNotFoundError/ValueError as ValueError with the offending value shown.","triggerScenarios":"Calling create_scheduled_run, next_due, to_job, or build_job_from_draft with tz set to something like 'PST', 'UTC+2', 'America/New_York ' (whitespace), or a typo like 'Europa/Berlin'. Note tz=None is allowed and returns early; only non-None invalid strings raise.","commonSituations":"Using POSIX tz strings ('US/Eastern', 'GMT+1') instead of IANA keys; carrying over timezone names from a UI dropdown or legacy config; deprecated/renamed zone keys across tzdata versions; missing tzdata package on Windows making all lookups fail.","solutions":["Use the exact IANA key, e.g. 'America/New_York', 'Europe/Berlin', 'UTC'","Strip/normalize user input before passing: tz = tz.strip() if tz else None","Validate eagerly in your own layer with zoneinfo.available_timezones() or a try/except ZoneInfo(tz) probe","On Windows, pip install tzdata if even valid keys fail","Pass None to accept the default timezone instead of guessing a string"],"exampleFix":"// before\njob = create_scheduled_run(..., tz=user_tz)  # user_tz = 'PST'\n\n// after\nfrom zoneinfo import ZoneInfo\n\ndef safe_tz(raw):\n    if raw is None:\n        return None\n    try:\n        ZoneInfo(raw)\n        return raw\n    except Exception:\n        return None  # fall back to default\n\njob = create_scheduled_run(..., tz=safe_tz(user_tz))","handlingStrategy":"validation","validationCode":"from zoneinfo import ZoneInfo\n\ndef is_valid_tz(tz):\n    if tz is None:\n        return True\n    try:\n        ZoneInfo(tz)\n        return True\n    except Exception:\n        return False\n\nassert is_valid_tz(\"America/New_York\")\nassert not is_valid_tz(\"PST\")","typeGuard":"from typing import Optional\nfrom zoneinfo import ZoneInfo\n\ndef valid_timezone(tz: object) -> Optional[str]:\n    \"\"\"Return tz if it is None or a valid IANA key, else None.\"\"\"\n    if tz is None:\n        return None\n    if isinstance(tz, str):\n        try:\n            ZoneInfo(tz)\n            return tz\n        except Exception:\n            return None\n    return None","tryCatchPattern":"from agent.src.scheduled_research.models import create_scheduled_run\n\ntry:\n    run = create_scheduled_run(..., tz=tz)\nexcept ValueError as exc:\n    if \"not a recognized IANA timezone\" in str(exc):\n        run = create_scheduled_run(..., tz=None)  # fall back to default\n    else:\n        raise","preventionTips":["Offer a timezone picker sourced from zoneinfo.available_timezones()","Strip and validate user-supplied timezone strings before persisting them","Cache validated timezone strings at the config layer"],"tags":["timezone","validation","scheduled-research","zoneinfo"],"backgroundTag":"invalid-timezone-identifier","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}