{"record":{"id":"291093e490c76645","repo":"python/cpython","slug":"microsecond-must-be-in-0-999999-not-microsecond","errorCode":null,"errorMessage":"microsecond must be in 0..999999, not {microsecond}","messagePattern":"microsecond must be in 0\\.\\.999999, not (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Lib/_pydatetime.py","lineNumber":593,"sourceCode":"        raise ValueError(f\"month must be in 1..12, not {month}\")\n    dim = _days_in_month(year, month)\n    if not 1 <= day <= dim:\n        raise ValueError(f\"day {day} must be in range 1..{dim} for month {month} in year {year}\")\n    return year, month, day\n\ndef _check_time_fields(hour, minute, second, microsecond, fold):\n    hour = _index(hour)\n    minute = _index(minute)\n    second = _index(second)\n    microsecond = _index(microsecond)\n    if not 0 <= hour <= 23:\n        raise ValueError(f\"hour must be in 0..23, not {hour}\")\n    if not 0 <= minute <= 59:\n        raise ValueError(f\"minute must be in 0..59, not {minute}\")\n    if not 0 <= second <= 59:\n        raise ValueError(f\"second must be in 0..59, not {second}\")\n    if not 0 <= microsecond <= 999999:\n        raise ValueError(f\"microsecond must be in 0..999999, not {microsecond}\")\n    if fold not in (0, 1):\n        raise ValueError(f\"fold must be either 0 or 1, not {fold}\")\n    return hour, minute, second, microsecond, fold\n\ndef _check_tzinfo_arg(tz):\n    if tz is not None and not isinstance(tz, tzinfo):\n        raise TypeError(\n            \"tzinfo argument must be None or of a tzinfo subclass, \"\n            f\"not {type(tz).__name__!r}\"\n        )\n\ndef _divide_and_round(a, b):\n    \"\"\"divide a by b and round result to the nearest integer\n\n    When the ratio is exactly half-way between two integers,\n    the even integer is returned.\n    \"\"\"\n    # Based on the reference implementation for divmod_near","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_pydatetime.py#L575-L611","documentation":"Raised by _check_time_fields() when the microsecond argument to time()/datetime() is not in 0..999999. A second holds at most 999999 microseconds; passing 1000000 or a nanosecond-scale value (which can reach 9 digits) fails this check.","triggerScenarios":"time(0, 0, 0, 1000000); passing a nanosecond timestamp's fractional part (e.g. 123456789) directly as microseconds; converting Java Instant.getNano() or time.time_ns() remainders without dividing by 1000.","commonSituations":"Interop with nanosecond-precision systems (Java, Go, time.time_ns(), pandas); unit mismatch when the source API's sub-second field is nanoseconds but the code assumes microseconds.","solutions":["Divide nanoseconds by 1000 before passing: us = ns // 1000","Carry overflow: sec += us // 1000000; us %= 1000000","Validate 0 <= microsecond <= 999999 on values from external APIs"],"exampleFix":"// before\ndt = datetime.fromtimestamp(ts, tz)\ndt = dt.replace(microsecond=ns_part)  # ns_part is nanoseconds\n// after\ndt = dt.replace(microsecond=ns_part // 1000)","handlingStrategy":"validation","validationCode":"if not 0 <= microsecond <= 999999:\n    raise ValueError('microsecond must be 0..999999')","typeGuard":"def valid_microsecond(us) -> bool:\n    return 0 <= us <= 999999","tryCatchPattern":null,"preventionTips":["Convert nanoseconds to microseconds (ns // 1000) from time_ns()/Java/pandas sources","Carry overflow: sec += us // 1_000_000; us %= 1_000_000"],"tags":["datetime","valueerror","validation","time","nanoseconds"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}