Skip to content

Error Codes money

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/money

Part of Error codes: every code @ultimat3/money registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_ALLOCATION_INVALID split ratios or part count are unusable zero parts, or all-zero ratios allocate(amount, 3) — a positive integer part count; or allocateByRatios(amount, [70, 20, 10]) — finite, non-negative, not all zero
X_CURRENCY_INVALID a registerCurrency declaration that cannot become a currency a code that is not three uppercase A–Z letters, an exponent that is not a whole number in 0…15 (MAX_MONEY_SCALE), or an empty name. Nothing is defaulted: a guessed exponent of 2 reads 1.23456789 as 1.23 and shifts every stored minor by a power of ten registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' }) — three A–Z letters, a whole exponent from 0 to 15, and a non-empty name
X_CURRENCY_MISMATCH two Money values in different currencies adding EUR to USD convert(value, '<target>', rate) first
X_CURRENCY_REDEFINED one currency code registered twice with different meanings a second registerCurrency for a code already in force — a shipped ISO row, or an earlier registration — carrying a different exponent or name. An identical second call is a no-op, so a module imported twice is not a crash; cause prints both declarations registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' }) — keep this one call and delete the other. Changing a live exponent means migrating every stored amount in that currency first — each one shifts by a power of ten
X_CURRENCY_UNKNOWN currency code not in the currency table a lowercase code — the lookup is exact — or a currency the shipped rows do not carry. 53 ISO-4217 rows ship, at packages/money/src/currency.ts:21, and As of 2026-08 they are not the whole set: registerCurrency() adds a row for this process, and currencyCodes() answers with those registrations included. Also raised where there is no currency at all to infer — sum([]) over an empty array assertCurrency('EUR') with a code currencyCodes() lists, uppercased; sum([], 'EUR') where nothing can be inferred — or declare the missing currency once at boot: registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' })
X_MONEY_INPUT_INVALID a typed amount could not be read in this locale the text holds a character the locale does not use in a number, separators in an order the locale never writes, or more fraction digits than the currency has parseAmount(text, { currency, locale }) — re-prompt the person; the cause names the character that stopped the read
X_MONEY_NOT_DECIMAL a fromDecimal input that is not a plain decimal string a number, null or undefined where a string was expected (a JSON body carrying 12.99), or a string with grouping separators, a currency symbol or exponent notation fromDecimal('12.99', 'USD') — send the amount as a decimal string; for text a person typed, parseAmount(text, { currency, locale })
X_MONEY_NOT_INTEGER a Money.minor that is not an integer a float leaked in, or a rescale() that would drop minor units fromDecimal('12.99', 'USD'), or pass an explicit rounding mode
X_MONEY_SCALE_INVALID a Money.scale that is not usable — either the exponent itself, or the one two operands would have to meet at a fractional, negative or out-of-range scale (15 is the last exponent whose power of ten is still a safe integer); or adding a coarse value to a fine one, where widening to their common scale overflows a safe integer fromMinor(minor, currency, 6) — a scale in range, 6 for micros; or omit it for the currency's own minor unit. On an overflow the cause names the finest scale that fits: rescale(value, <scale>, 'half-up')
X_RATE_MISSING no FX rate for the pair no RateProvider registered convertWith(fixedRateProvider({ 'USD/EUR': 0.92 }, new Date('2026-03-14T00:00:00Z')), amount, 'EUR') — a RateProvider that covers the pair; there is no default, because a wrong rate is worse than a missing one

Clone this wiki locally