{"record":{"id":"556aedd85a6af7fc","repo":"JamesNK/Newtonsoft.Json","slug":"invalid-date-time-handling-value","errorCode":null,"errorMessage":"Invalid date time handling value.","messagePattern":"Invalid date time handling value\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"Src/Newtonsoft.Json/Utilities/DateTimeUtils.cs","lineNumber":109,"sourceCode":"#endif\n\n        internal static DateTime EnsureDateTime(DateTime value, DateTimeZoneHandling timeZone)\n        {\n            switch (timeZone)\n            {\n                case DateTimeZoneHandling.Local:\n                    value = SwitchToLocalTime(value);\n                    break;\n                case DateTimeZoneHandling.Utc:\n                    value = SwitchToUtcTime(value);\n                    break;\n                case DateTimeZoneHandling.Unspecified:\n                    value = new DateTime(value.Ticks, DateTimeKind.Unspecified);\n                    break;\n                case DateTimeZoneHandling.RoundtripKind:\n                    break;\n                default:\n                    throw new ArgumentException(\"Invalid date time handling value.\");\n            }\n\n            return value;\n        }\n\n        private static DateTime SwitchToLocalTime(DateTime value)\n        {\n            switch (value.Kind)\n            {\n                case DateTimeKind.Unspecified:\n                    return new DateTime(value.Ticks, DateTimeKind.Local);\n\n                case DateTimeKind.Utc:\n                    return value.ToLocalTime();\n\n                case DateTimeKind.Local:\n                    return value;\n            }","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/JamesNK/Newtonsoft.Json/blob/4f73e74372445108d2c1bda37b36e6f5e43402e0/Src/Newtonsoft.Json/Utilities/DateTimeUtils.cs#L91-L127","documentation":"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.","triggerScenarios":"An invalid DateTimeZoneHandling value reaches EnsureDateTime — e.g. JsonSerializerSettings.DateTimeZoneHandling set to (DateTimeZoneHandling)99 via an explicit cast, or corrupted/in-memory settings.","commonSituations":"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.","solutions":["Only use the defined DateTimeZoneHandling values (Local, Utc, Unspecified, RoundtripKind).","Validate the enum value with Enum.IsDefined before assigning settings.DateTimeZoneHandling.","Sanitize any settings deserialized from external config before applying them to the serializer."],"exampleFix":"// before\nsettings.DateTimeZoneHandling = (DateTimeZoneHandling)99; // invalid -> throws on use\n// after\nsettings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind;","handlingStrategy":"validation","validationCode":"// Validate the DateTimeZoneHandling value before applying settings.\nvar dz = settings.DateTimeZoneHandling;\nif (!Enum.IsDefined(typeof(DateTimeZoneHandling), dz))\n    throw new ArgumentOutOfRangeException(nameof(settings.DateTimeZoneHandling), $\"Invalid value {dz}.\");","typeGuard":"static bool IsValid(DateTimeZoneHandling h) => Enum.IsDefined(typeof(DateTimeZoneHandling), h);","tryCatchPattern":"try { JsonConvert.SerializeObject(obj, settings); } catch (ArgumentException ex) when (ex.Message.Contains(\"Invalid date time handling\")) { settings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind; }","preventionTips":["Only assign defined DateTimeZoneHandling values.","Validate enum-typed settings with Enum.IsDefined when they come from config.","Sanitize deserialized settings before use."],"tags":["datetime","configuration","newtonsoft-json","defensive"],"analyzedSha":"4f73e74372445108d2c1bda37b36e6f5e43402e0","analyzedAt":"2026-08-07T06:10:08.596Z","schemaVersion":2},"datasetVersion":"2026-08-07T07:17:06.508Z"}