Profiles·Public

luxon

semver>=3.2.1postconditions29functions27last verified2026-06-23coverage score73%

Postconditions — what we check

DateTime.fromISO · fromiso-invalid-date
warning
Wheninput string is not a valid ISO 8601 format
ReturnsInvalid DateTime object (dt.isValid is false, dt.invalidReason contains error)
Required handlingCaller MUST check isValid property before using the DateTime object. Invalid DateTime objects contain error information in invalidReason and invalidExplanation. Without validation, invalid dates cause calculation errors, display issues, or data corruption. import { DateTime } from 'luxon'; const dt = DateTime.fromISO(apiResponse.timestamp); if (!dt.isValid) { throw new Error(`Invalid ISO timestamp: ${dt.invalidReason}`); } // Safe to use dt now Do NOT pass Invalid DateTimes to formatting, diff, or arithmetic methods without checking isValid.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[1][2]
DateTime.fromFormat · fromformat-missing-args
error
WhenEither the text argument or the format argument is undefined or null. This is a developer error — not a user input error. Common when the format argument comes from a variable that was not properly initialized.
ThrowsInvalidArgumentError: fromFormat requires an input string and a format
Required handlingAlways ensure both arguments are non-null strings before calling fromFormat(): import { DateTime } from 'luxon'; // WRONG — throws if format is undefined const dt = DateTime.fromFormat(userInput, formatFromConfig); // crashes if config missing // CORRECT — validate arguments first if (!formatFromConfig) { throw new Error('Date format configuration is missing'); } const dt = DateTime.fromFormat(userInput, formatFromConfig); This is thrown synchronously, so it will crash any route handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[3]
DateTime.fromFormat · fromformat-invalid-date
warning
Wheninput string does not match the specified format
ReturnsInvalid DateTime object (dt.isValid is false, dt.invalidReason contains error)
Required handlingCaller MUST check isValid property after parsing. Invalid DateTime objects indicate parsing failure but do not throw. import { DateTime } from 'luxon'; const dt = DateTime.fromFormat(userInput, 'MM/dd/yyyy'); if (!dt.isValid) { return res.status(400).json({ error: `Invalid date: ${dt.invalidReason}` }); }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[4]
DateTime.fromSQL · fromsql-invalid-date
warning
Wheninput string is not a valid SQL date format
ReturnsInvalid DateTime object (dt.isValid is false)
Required handlingCaller MUST check isValid property. Invalid SQL dates can cause database query errors and data corruption. import { DateTime } from 'luxon'; const dt = DateTime.fromSQL(input); if (!dt.isValid) { throw new Error(`Invalid SQL date: ${dt.invalidReason}`); }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[5]
DateTime.fromHTTP · fromhttp-invalid-date
warning
Wheninput string is not a valid HTTP date format
ReturnsInvalid DateTime object (dt.isValid is false)
Required handlingCaller MUST check isValid property. Invalid HTTP dates can cause caching errors and incorrect header processing. import { DateTime } from 'luxon'; const dt = DateTime.fromHTTP(httpHeaderValue); if (!dt.isValid) { /* handle invalid HTTP date */ }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[6]
DateTime.fromRFC2822 · fromrfc2822-invalid-date
warning
Wheninput string is not a valid RFC 2822 format
ReturnsInvalid DateTime object (dt.isValid is false)
Required handlingCaller MUST check isValid property. import { DateTime } from 'luxon'; const dt = DateTime.fromRFC2822(emailDate); if (!dt.isValid) { /* handle invalid RFC 2822 date */ }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[7]
DateTime.fromObject · fromobject-conflicting-specification
error
WhenThe object mixes mutually exclusive field sets. Two patterns that throw: 1. weekYear or weekNumber is combined with year, month, day, or ordinal 2. ordinal (day-of-year) is combined with month or day These are developer errors — calendar systems cannot be mixed in a single object.
ThrowsConflictingSpecificationError: "Can't mix weekYear/weekNumber units with year/month/day or ordinals" or "Can't mix ordinal dates with month/day"
Required handlingUse only one calendar system per DateTime.fromObject() call: import { DateTime } from 'luxon'; // WRONG — mixes ISO week date with Gregorian — throws ConflictingSpecificationError DateTime.fromObject({ weekYear: 2023, weekNumber: 5, month: 2, day: 1 }); // WRONG — mixes ordinal with month/day DateTime.fromObject({ ordinal: 45, month: 2, day: 14 }); // CORRECT — ISO week date only DateTime.fromObject({ weekYear: 2023, weekNumber: 5, weekday: 1 }); // CORRECT — Gregorian only DateTime.fromObject({ year: 2023, month: 2, day: 1 }); // CORRECT — ordinal only (day of year) DateTime.fromObject({ year: 2023, ordinal: 45 }); This throws synchronously and will crash route handlers without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[8][9]
DateTime.fromObject · fromobject-invalid-date
warning
Whenobject contains invalid date values (e.g., month 13, day 400)
ReturnsInvalid DateTime object (dt.isValid is false)
Required handlingCaller MUST check isValid property. Invalid calendar values (February 30, 25:00, month 13) produce invalid DateTimes. import { DateTime } from 'luxon'; const dt = DateTime.fromObject({ year: 2023, month: 2, day: 30 }); // dt.isValid === false, dt.invalidReason === 'unit out of range' if (!dt.isValid) { /* handle */ }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[9]
DateTime.fromMillis · frommillis-non-number-throws
error
WhenThe milliseconds argument is not a number. Common causes: - API response returns timestamp as a string (e.g., "1682506800000") - Database record has null or undefined timestamp (user.createdAt === null) - JavaScript arithmetic on non-number produces NaN Note: Out-of-range timestamps (beyond ±8.64e15 ms) return Invalid DateTime (no throw). Note: NaN is technically a number in JavaScript, so NaN does NOT trigger this throw — it produces an Invalid DateTime instead.
ThrowsInvalidArgumentError: "fromMillis requires a numerical input, but received a string with value 1682506800000" (error message includes the type and value of the invalid argument)
Required handlingValidate or coerce the argument before calling fromMillis(): import { DateTime } from 'luxon'; // WRONG — throws if timestamp is null or string const dt = DateTime.fromMillis(record.createdAt); // CORRECT — validate first const ts = Number(record.createdAt); if (!isFinite(ts)) { throw new Error(`Invalid timestamp: ${record.createdAt}`); } const dt = DateTime.fromMillis(ts); // Also CORRECT — use fromJSDate for Date objects const dt = DateTime.fromJSDate(new Date(record.createdAt)); if (!dt.isValid) { /* handle */ }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[10][11]
DateTime.fromSeconds · fromseconds-non-number-throws
error
WhenThe seconds argument is not a number. Common when Unix timestamps come from APIs as strings, or when database values are null/undefined. Note that NaN (JavaScript "Not a Number") is typeof === "number", so NaN does NOT trigger this throw — NaN*1000 = NaN, which produces an Invalid DateTime with "Timestamp out of range".
ThrowsInvalidArgumentError: fromSeconds requires a numerical input
Required handlingValidate or coerce the argument before calling fromSeconds(): import { DateTime } from 'luxon'; // WRONG — throws if seconds is null, undefined, or string const dt = DateTime.fromSeconds(apiResponse.expires_at); // CORRECT — coerce and validate const secs = Number(apiResponse.expires_at); if (!Number.isFinite(secs)) { throw new Error('Missing or invalid expiry timestamp'); } const dt = DateTime.fromSeconds(secs); if (!dt.isValid) { /* handle out-of-range */ }
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[12][11]
DateTime.startOf · startof-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Valid values are: 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond' (also 'years', 'months', etc. plural forms). Common mistakes: 'date' (use 'day'), 'hours' (valid), 'min' (use 'minute'), 'secs' (use 'second'), or unit from a different library (e.g., moment.js or date-fns unit names that differ). Note: Called on an Invalid DateTime, startOf() returns the Invalid DateTime — no throw.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingAlways use valid luxon unit strings. Validate dynamically-sourced unit strings before use: import { DateTime } from 'luxon'; // WRONG — throws if unit is 'date' or any unrecognized string const start = DateTime.now().startOf(userSelectedUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['year', 'month', 'week', 'day', 'hour', 'minute', 'second']; if (!VALID_UNITS.includes(unit)) { throw new Error(`Invalid date unit: ${unit}`); } const start = DateTime.now().startOf(unit);
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[13][14]
DateTime.endOf · endof-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Same valid unit set as startOf(): 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond'. Throws for 'date', 'min', 'secs', or any unit string not in luxon's vocabulary.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingSame as startOf() — always validate dynamically-sourced unit strings before use: import { DateTime } from 'luxon'; const VALID_UNITS = ['year', 'month', 'week', 'day', 'hour', 'minute', 'second']; if (!VALID_UNITS.includes(unit)) { throw new Error(`Invalid date unit: ${unit}`); } const end = DateTime.now().endOf(unit);
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[15][16]
DateTime.min · min-non-datetime-throws
error
WhenAny argument is not a luxon DateTime instance. Common mistakes: - Passing a JavaScript Date object (use DateTime.fromJSDate(d) first) - Passing a millisecond timestamp (use DateTime.fromMillis(ms) first) - Passing null or undefined (e.g., from an optional date field) - Mixing luxon DateTime with dates from other libraries (moment, dayjs) Note: DateTime.min() with zero arguments returns undefined (no throw).
ThrowsInvalidArgumentError: min requires all arguments be DateTimes
Required handlingEnsure all arguments are luxon DateTime instances: import { DateTime } from 'luxon'; // WRONG — throws for JS Date or non-DateTime arguments const earliest = DateTime.min(date1, new Date(), timestamp); // CORRECT — convert JS Dates first const dtArray = [date1, jsDate, ts].map(d => { if (DateTime.isDateTime(d)) return d; if (d instanceof Date) return DateTime.fromJSDate(d); if (typeof d === 'number') return DateTime.fromMillis(d); throw new Error(`Cannot convert to DateTime: ${d}`); }); const earliest = DateTime.min(...dtArray);
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[17][18]
DateTime.max · max-non-datetime-throws
error
WhenAny argument is not a luxon DateTime instance. Same causes as min-non-datetime-throws. Note: DateTime.max() with zero arguments returns undefined (no throw).
ThrowsInvalidArgumentError: max requires all arguments be DateTimes
Required handlingSame as DateTime.min() — ensure all arguments are luxon DateTime instances before passing. import { DateTime } from 'luxon'; // WRONG — throws if any date is a JS Date object or null const latest = DateTime.max(dt1, jsDate, null); // CORRECT const latest = DateTime.max(...validDateTimes.filter(DateTime.isDateTime));
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[19][20]
DateTime.set · set-conflicting-specification
error
WhenThe values object mixes mutually exclusive calendar field sets. Two patterns that throw: 1. weekYear or weekNumber is combined with year, month, day, or ordinal 2. ordinal (day-of-year) is combined with month or day Note: Mixing ISO weekday fields (weekday) with localWeekday also throws (not supported). When called on an Invalid DateTime, returns Invalid — no throw.
ThrowsConflictingSpecificationError: "Can't mix weekYear/weekNumber units with year/month/day or ordinals" or "Can't mix ordinal dates with month/day"
Required handlingUse only one calendar system per set() call: import { DateTime } from 'luxon'; // WRONG — mixes ISO week date with Gregorian — throws ConflictingSpecificationError dt.set({ weekYear: 2023, weekNumber: 5, month: 2 }); // WRONG — mixes ordinal with month/day dt.set({ ordinal: 45, month: 2, day: 14 }); // CORRECT — change Gregorian fields only dt.set({ year: 2023, month: 2, day: 1 }); // CORRECT — change ISO week date fields only dt.set({ weekYear: 2023, weekNumber: 5, weekday: 1 }); This throws synchronously and will crash route handlers without try-catch. Less common than fromObject() conflicts but dangerous when building date manipulation utilities where the field set is determined at runtime.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[21][22]
DateTime.diff · diff-invalid-unit
error
WhenThe unit argument (or any element of a unit array) is not a recognized luxon unit string. Valid units are: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (singular forms also accepted). Common mistakes: 'date' (use 'day'), 'min' (use 'minute'), 'secs' (use 'second'), passing a moment.js or date-fns unit name that differs from luxon's vocabulary. Note: If either DateTime is invalid, diff() returns an invalid Duration — no throw.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingAlways use valid luxon unit strings. Validate dynamically-sourced unit strings: import { DateTime } from 'luxon'; // WRONG — throws if unit is 'date', 'min', or any unrecognized string const duration = start.diff(end, userSelectedUnit); // CORRECT — validate against known unit list const VALID_DIFF_UNITS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_DIFF_UNITS.includes(unit)) { throw new Error(`Invalid diff unit: ${unit}`); } const duration = start.diff(end, unit); // CORRECT — use multiple units safely const duration = start.diff(end, ['months', 'days']);
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[23][24]
DateTime.plus · plus-non-duration-throws
error
WhenThe duration argument is a string (e.g. '1d', 'P1D'), undefined, null, boolean, or any value other than (a) a Duration instance, (b) a finite number of milliseconds, or (c) a plain object. Common causes: - API/config supplies duration as ISO string ('P1D') — must parse with Duration.fromISO() first - Optional config field is undefined — dt.plus(config.gracePeriod) crashes if absent - Database returns NULL for a duration column — same crash - Number-like string from a query param ('30') — typeof is 'string', not 'number' - NaN — DOES throw (via Duration.fromMillis(NaN).plus()), error message says "Invalid unit value NaN" Note: When called on an Invalid DateTime, plus() returns the Invalid DateTime unchanged.
ThrowsInvalidArgumentError: "Unknown duration argument <value> of type <typeof>" (e.g. "Unknown duration argument 1d of type string", "Unknown duration argument undefined of type undefined") When passed NaN: "Invalid unit value NaN" (from Duration.fromMillis arithmetic)
Required handlingConvert the input to a Duration instance, milliseconds number, or plain object before calling plus(): import { DateTime, Duration } from 'luxon'; // WRONG — throws "Unknown duration argument P1D of type string" const expires = DateTime.now().plus(config.gracePeriod); // crashes if config.gracePeriod is 'P1D' // WRONG — throws if invoiceTermDays is null/undefined const due = DateTime.now().plus({ days: invoice.termDays }); // crashes on null term // CORRECT — parse ISO duration strings explicitly const gracePeriod = Duration.fromISO(config.gracePeriod); if (!gracePeriod.isValid) throw new Error(`Invalid grace period: ${config.gracePeriod}`); const expires = DateTime.now().plus(gracePeriod); // CORRECT — guard config values const days = Number(invoice.termDays); if (!Number.isFinite(days)) throw new Error('Missing term days'); const due = DateTime.now().plus({ days }); This throws synchronously and will crash any route handler without try-catch.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[25][26][27]
DateTime.minus · minus-non-duration-throws
error
WhenSame triggers as plus-non-duration-throws — the duration argument is a string, undefined, null, boolean, or any value other than a Duration / millisecond number / plain object. Common causes: - Lookback window from URL query string ('7d') passed directly to minus() - Optional retention period from config is undefined - User clears a "days ago" form field, leaving null
ThrowsInvalidArgumentError: "Unknown duration argument <value> of type <typeof>"
Required handlingSame as plus() — convert to a Duration instance, milliseconds number, or plain object first: import { DateTime } from 'luxon'; // WRONG — throws if lookbackParam is '7d' or null const since = DateTime.now().minus(lookbackParam); // CORRECT — coerce to integer days first const days = Number(lookbackParam); if (!Number.isFinite(days) || days < 0) { return res.status(400).json({ error: 'Invalid lookback period' }); } const since = DateTime.now().minus({ days }); This throws synchronously and will crash any route handler without try-catch. Especially dangerous in reporting/analytics endpoints where lookback windows come from untrusted query parameters.
costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[28][26][29]
Duration.shiftTo · shiftto-invalid-unit
error
WhenOne or more arguments to shiftTo() is not a recognized luxon unit string. Valid values are: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (singular forms also accepted). Common mistakes: 'date' (use 'day'), 'min' (use 'minute'), 'secs' (use 'second'), or unit strings from a different library (moment.js, date-fns) that differ from luxon's vocabulary. Note: shiftTo() with zero arguments returns the original Duration unchanged. Note: Called on an Invalid Duration, shiftTo() returns the Invalid Duration — no throw.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate dynamically-sourced unit strings before passing to shiftTo(): import { Duration } from 'luxon'; // WRONG — throws if userUnit is 'date', 'min', or any unrecognized string const display = Duration.fromMillis(elapsed).shiftTo(userUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(userUnit)) { throw new Error(`Invalid duration unit: ${userUnit}`); } const display = Duration.fromMillis(elapsed).shiftTo(userUnit); This throws synchronously and will crash any route handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[30][31][32]
Duration.as · duration-as-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Same valid set as shiftTo() — 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (plus singular forms). Common mistakes: 'date', 'min', 'secs', or units from moment.js / date-fns. Note: Called on an Invalid Duration, as() returns NaN — no throw. The throw only happens when the Duration is valid but the unit string is bad.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate dynamically-sourced unit strings before calling as(): import { Duration } from 'luxon'; // WRONG — throws if userUnit is 'min' or 'secs' or other bad value const totalDays = Duration.fromMillis(elapsed).as(userUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(userUnit)) { throw new Error(`Invalid duration unit: ${userUnit}`); } const total = Duration.fromMillis(elapsed).as(userUnit); This throws synchronously and will crash route handlers without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[33][31][34]
Duration.get · duration-get-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Same valid set as as() and shiftTo() — 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (plus singular forms). Common mistakes: 'date', 'min', 'secs', or units from other date libraries. Unlike as(), get() throws even when called on an Invalid Duration — normalizeUnit() runs unconditionally before the property lookup.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate dynamically-sourced unit strings before calling get(): import { Duration } from 'luxon'; // WRONG — throws if unitName is 'date' or any unrecognized string const minutes = duration.get(unitName); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(unitName)) { throw new Error(`Invalid duration unit: ${unitName}`); } const value = duration.get(unitName); This throws synchronously. Particularly common in template engines where the unit comes from a config or column name.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[35][31][36]
Duration.fromObject · duration-fromobject-non-object-throws
error
WhenThe obj argument is null, undefined, a string, a number, or any non-object value. Common causes: - Config value is missing: `Duration.fromObject(config.retryDelay)` where config key is absent (resolves to undefined) - API response field is null: `Duration.fromObject(data.duration)` when duration is not set - Passing a Duration instance (not a plain object) — this is allowed - Passing a number of milliseconds — this is NOT allowed (use Duration.fromMillis())
ThrowsInvalidArgumentError: "Duration.fromObject: argument expected to be an object, got null" or "...got undefined" or "...got number" etc.
Required handlingValidate or default the argument before calling Duration.fromObject(): import { Duration } from 'luxon'; // WRONG — throws if config.delay is undefined or null const delay = Duration.fromObject(config.delay); // CORRECT — validate first if (!config.delay || typeof config.delay !== 'object') { throw new Error('Missing or invalid duration configuration'); } const delay = Duration.fromObject(config.delay); // ALSO CORRECT — provide a fallback const delay = Duration.fromObject(config.delay ?? { milliseconds: 1000 }); Note: Use Duration.fromMillis() for numeric values, not fromObject().
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[37][38]
DateTime.hasSame · hassame-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Valid values are: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (and singular forms). Common mistakes: 'date' (use 'day'), 'week-of-year' (no such unit), unit strings copied from moment.js or date-fns vocabularies that differ from luxon's. Dynamic unit strings from config, URL query, or user input are the most common source.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingRestrict dynamically-sourced unit strings to luxon's vocabulary before calling hasSame(): import { DateTime } from 'luxon'; // WRONG — throws if groupBy is 'date' or any unrecognized value const sameGroup = dtA.hasSame(dtB, groupBy); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(groupBy)) { throw new Error(`Invalid grouping unit: ${groupBy}`); } const sameGroup = dtA.hasSame(dtB, groupBy); This throws synchronously and will crash any handler without try-catch. Especially common in analytics/reporting endpoints where the grouping unit comes from a URL query parameter.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[39][40][41]
Duration.plus · duration-plus-non-duration-throws
error
WhenThe duration argument is a string, undefined, null, boolean, or any value other than a Duration instance, a millisecond number, or a plain object. Common causes: - Backoff increment from config is undefined (key missing) - String value from environment variable passed directly ('30s') - Optional duration field on API request is null - Confusion with moment.js .add() which accepted strings
ThrowsInvalidArgumentError: "Unknown duration argument <value> of type <typeof>"
Required handlingConvert the duration argument to a Duration / number / plain object before adding: import { Duration } from 'luxon'; // WRONG — throws if increment is undefined or a string like '30s' const total = baseWindow.plus(increment); // CORRECT — coerce to plain object first if (typeof increment !== 'object' || increment === null) { throw new Error('Invalid duration increment'); } const total = baseWindow.plus(increment); // ALSO CORRECT — wrap milliseconds const total = baseWindow.plus({ milliseconds: Number(envMs) || 0 }); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[42][26][43]
Duration.minus · duration-minus-non-duration-throws
error
WhenSame triggers as duration-plus-non-duration-throws — the argument is a string, undefined, null, boolean, or any value other than a Duration / millisecond number / plain object. Common causes: - Pause/grace period from config is undefined - String value from environment variable passed directly - Optional retention reduction is null
ThrowsInvalidArgumentError: "Unknown duration argument <value> of type <typeof>"
Required handlingSame as Duration.plus — convert to Duration / number / plain object first: import { Duration } from 'luxon'; // WRONG — throws if pauseInterval is '30s' or undefined const remaining = baseWindow.minus(pauseInterval); // CORRECT — restrict to plain objects const safePause = (typeof pauseInterval === 'object' && pauseInterval !== null) ? pauseInterval : { milliseconds: 0 }; const remaining = baseWindow.minus(safePause); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[44][26][45]
Duration.set · duration-set-invalid-unit
error
WhenThe values object contains a key that is not a recognized luxon unit string. Valid keys are: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (and singular forms). Common mistakes: 'date' (use 'days'), 'min' (use 'minutes'), 'sec' (use 'seconds'), or merging a generic config object that contains unrelated keys alongside the unit keys.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingRestrict the values object to luxon unit keys before calling set(): import { Duration } from 'luxon'; // WRONG — throws if userValues contains any unrecognized key const updated = base.set(userValues); // CORRECT — filter to valid unit keys const VALID_UNITS = ['years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; const safeValues = Object.fromEntries( Object.entries(userValues).filter(([k]) => VALID_UNITS.includes(k)) ); const updated = base.set(safeValues); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[46][31][47]
Interval.length · interval-length-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Valid values are: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds' (and singular forms). Most common cause: the unit comes from a URL query parameter, user preference, or config value without validation. Note: if the Interval itself is invalid (e.g., end before start), length() returns NaN unconditionally and does NOT throw — the throw only fires on a valid Interval with an unrecognized unit.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate the unit argument before calling length(): import { Interval } from 'luxon'; // WRONG — throws if displayUnit is 'date' or any unrecognized value const labelValue = sessionInterval.length(displayUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(displayUnit)) { displayUnit = 'milliseconds'; } const labelValue = sessionInterval.length(displayUnit); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[48][31][49]
Interval.count · interval-count-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Same valid-values list as length(). Most common cause: dynamic unit string from URL query / config / user preference. Note: if the Interval itself is invalid, count() returns NaN and does NOT throw — the throw only fires when the Interval is valid but the unit is not.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate the unit argument before calling count(): import { Interval } from 'luxon'; // WRONG — throws if periodUnit is 'date' or any unrecognized value const billingDays = interval.count(periodUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(periodUnit)) { throw new Error(`Invalid period unit: ${periodUnit}`); } const billingDays = interval.count(periodUnit); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[50][40][51]
Interval.toDuration · interval-toduration-invalid-unit
error
WhenThe unit argument is not a recognized luxon unit string. Same valid-values list as length()/count(). Most common cause: passing through a unit string from a generic "groupBy" or "reportUnit" config without validating. Note: if the Interval itself is invalid, toDuration() returns Invalid Duration and does NOT throw — the throw fires only when the Interval is valid but the unit is not.
ThrowsInvalidUnitError: Invalid unit <unit>
Required handlingValidate the unit argument before calling toDuration(): import { Interval } from 'luxon'; // WRONG — throws if reportUnit is 'date' or any unrecognized value const elapsed = interval.toDuration(reportUnit); // CORRECT — restrict to valid units const VALID_UNITS = ['years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds']; if (!VALID_UNITS.includes(reportUnit)) { throw new Error(`Invalid report unit: ${reportUnit}`); } const elapsed = interval.toDuration(reportUnit); This throws synchronously and will crash any handler without try-catch.
costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
Sources[52][53][54]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

Need a different package?

Request a profile