JamesNK/Newtonsoft.Json · error · ArgumentException

Invalid date time handling value.

Error message

Invalid date time handling value.

What it means

EnsureDateTime (DateTimeUtils.cs:93-113) applies the configured DateTimeZoneHandling to a parsed DateTime. The four defined enum values (Local, Utc, Unspecified, RoundtripKind) are all handled; the default branch at DateTimeUtils.cs:109 is a defensive guard that throws ArgumentException for an unexpected/invalid timeZone value — typically one produced by casting an out-of-range integer to DateTimeZoneHandling.

Source

Thrown at Src/Newtonsoft.Json/Utilities/DateTimeUtils.cs:109

#endif

        internal static DateTime EnsureDateTime(DateTime value, DateTimeZoneHandling timeZone)
        {
            switch (timeZone)
            {
                case DateTimeZoneHandling.Local:
                    value = SwitchToLocalTime(value);
                    break;
                case DateTimeZoneHandling.Utc:
                    value = SwitchToUtcTime(value);
                    break;
                case DateTimeZoneHandling.Unspecified:
                    value = new DateTime(value.Ticks, DateTimeKind.Unspecified);
                    break;
                case DateTimeZoneHandling.RoundtripKind:
                    break;
                default:
                    throw new ArgumentException("Invalid date time handling value.");
            }

            return value;
        }

        private static DateTime SwitchToLocalTime(DateTime value)
        {
            switch (value.Kind)
            {
                case DateTimeKind.Unspecified:
                    return new DateTime(value.Ticks, DateTimeKind.Local);

                case DateTimeKind.Utc:
                    return value.ToLocalTime();

                case DateTimeKind.Local:
                    return value;
            }

View on GitHub (pinned to 4f73e74372)

Solutions

1. Only use the defined DateTimeZoneHandling values (Local, Utc, Unspecified, RoundtripKind).
2. Validate the enum value with Enum.IsDefined before assigning settings.DateTimeZoneHandling.
3. Sanitize any settings deserialized from external config before applying them to the serializer.

Example fix

// before
settings.DateTimeZoneHandling = (DateTimeZoneHandling)99; // invalid -> throws on use
// after
settings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind;

// Validate the DateTimeZoneHandling value before applying settings.
var dz = settings.DateTimeZoneHandling;
if (!Enum.IsDefined(typeof(DateTimeZoneHandling), dz))
    throw new ArgumentOutOfRangeException(nameof(settings.DateTimeZoneHandling), $"Invalid value {dz}.");

static bool IsValid(DateTimeZoneHandling h) => Enum.IsDefined(typeof(DateTimeZoneHandling), h);

try { JsonConvert.SerializeObject(obj, settings); } catch (ArgumentException ex) when (ex.Message.Contains("Invalid date time handling")) { settings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind; }

When it happens

Trigger: An invalid DateTimeZoneHandling value reaches EnsureDateTime — e.g. JsonSerializerSettings.DateTimeZoneHandling set to (DateTimeZoneHandling)99 via an explicit cast, or corrupted/in-memory settings.

Common situations: Custom code casting arbitrary integers to DateTimeZoneHandling; deserialization of settings from untrusted/external config that produced an undefined enum value; very rare in normal usage.

Related errors

• Could not resolve type '{0}'. You may need to add a referenc
• Enum name '{0}' already exists on enum '{1}'.
• Enum type {0} is not a set of flags.
• Integer string '{0}' is not allowed.
• Unexpected value when converting date. Expected DateTime or

AI-assisted analysis of JamesNK/Newtonsoft.Json@4f73e74372 (2026-08-07). Data as JSON: /api/errors/556aedd85a6af7fc. Report an issue: GitHub.