What causes "Invalid locale '${locale}'" in validatorjs/validator.js?

Use the exact ISO-ish keys the table expects ('US', 'GB', 'PT', ...) or 'any'

validatorjs/validator.js · error · Error

Invalid locale '${locale}'

Error message

Invalid locale '${locale}'

What it means

isPostalCode(str, locale) validates postal codes against locale-specific regexes (e.g. 'US', 'GB', 'FR', or 'any'). An unsupported locale throws this error instead of returning false, because a missing locale entry is a caller configuration problem.

Source

Thrown at src/lib/isPostalCode.js:104

export default function isPostalCode(str, locale) {
  assertString(str);
  if (locale in patterns) {
    return patterns[locale].test(str);
  } else if (locale === 'any') {
    for (const key in patterns) {
      // https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md#ignoring-code-for-coverage-purposes
      // istanbul ignore else
      if (patterns.hasOwnProperty(key)) {
        const pattern = patterns[key];
        if (pattern.test(str)) {
          return true;
        }
      }
    }
    return false;
  }
  throw new Error(`Invalid locale '${locale}'`);
}

View on GitHub (pinned to a79ff980ab)

Solutions

Use the exact ISO-ish keys the table expects ('US', 'GB', 'PT', ...) or 'any'
Upper-case and trim the country code before calling
Validate the key with the module's exported locales list first
Upgrade validator.js if the needed locale was added in a newer version

Example fix

// before
validator.isPostalCode(zip, order.country); // 'usa' -> throws
// after
validator.isPostalCode(zip, (order.country || '').toUpperCase() === 'USA' ? 'US' : order.country);

Defensive patterns

Strategy: validation

Validate before calling

import { locales as postalLocales } from 'validator';
const norm = String(country || '').trim().toUpperCase();
const locale = postalLocales.includes(norm) ? norm : 'any';
validator.isPostalCode(zip, locale);

Type guard

const isValidPostalLocale = (loc) => typeof loc === 'string' && postalLocales.includes(loc);

Try / catch

let ok;
try { ok = validator.isPostalCode(zip, locale); }
catch (e) { if (/^Invalid locale/.test(e.message)) { ok = validator.isPostalCode(zip, 'any'); } else { throw e; } }

Prevention

Normalize country codes to uppercase two-letter form before calling
Use 'any' when the country is unknown rather than guessing a key
Keep a country->locale mapping tested against validator's locales list
Upgrade validator.js when a needed country key is missing

When it happens

Trigger: isPostalCode('94105', 'usa') (must be 'US'), isPostalCode(zip, country) where country is 'USA' or lowercase, locale variable undefined.

Common situations: Feeding full country names or ISO3 codes from shipping databases into the validator; case mismatches; new country added in a newer validator.js than installed.

Related errors

AI-assisted analysis of validatorjs/validator.js@a79ff980ab (2026-08-31). Data as JSON: /api/errors/4820210086524920. Report an issue: GitHub.