medusajs/medusa · error · MedusaError

Currency code needs to be a string

Error message

Currency code needs to be a string

What it means

normalizeCurrencyCode requires its argument to be a string and throws INVALID_ARGUMENT otherwise. It is applied throughout carts, orders, product imports, and filters to lowercase currency codes.

Source

Thrown at packages/core/utils/src/common/normalize-currency-code.ts:9

import { MedusaError, MedusaErrorTypes } from "./errors"
import { isString } from "./is-string"

/**
 * Normalizes `currencyCode` by transforming it to lowercase
 */
export function normalizeCurrencyCode(currencyCode: string) {
    if (!isString(currencyCode)) {
        throw new MedusaError(MedusaErrorTypes.INVALID_ARGUMENT, "Currency code needs to be a string")
    }

    return currencyCode.toLowerCase()
}

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Default or require currency_code upstream (derive from region/cart before calling)
2. Coerce/validate with zod or a manual string check before calling the API/workflow
3. Fix the data source to always provide an uppercase/lowercase 3-letter string

Example fix

// before
await cartService.addLineItem(cartId, { variant_id, quantity }) // missing currency
// after
const currency = z.string().length(3).parse(cart.currency_code)
await lineItemOps({ ...item, currency_code: currency })

const cur = input.currency_code ?? cart?.currency_code ?? region?.currency_code
if (typeof cur !== 'string' || cur.length !== 3) throw new Error('currency_code required')

const isCurrencyCode = (v: unknown): v is string => typeof v === 'string' && /^[a-zA-Z]{3}$/.test(v)

When it happens

Trigger: Passing undefined/null/number as currencyCode, e.g. adding a cart line without currency_code, or importing variants whose currency column is empty.

Common situations: Optional currency fields flowing from CSV import rows, third-party price feeds sending numbers ("100" vs 100), or requests missing the region/currency context.

Related errors

• The email is not valid
• invalid_data
• Cannot add promotions to campaign where currency_code don't
• --paths must be a directory - ${additionalPath}
• --base must be a file - ${baseFile}

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/e62e6356fd0008d9. Report an issue: GitHub.