PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Invalid locale code '{$locale}'

Error message

Invalid locale code '{$locale}'

What it means

NumberBase::validateLocale() enforces the Locale::STRUCTURE regex before ICU is consulted: exactly a 2-letter language, optionally a 4-letter script and/or 2-letter country, separated by '-' or '_'. Anything else — 3-letter language codes, 3-letter countries, free text, extra variants — is rejected as an invalid locale code.

Source

Thrown at src/PhpSpreadsheet/Style/NumberFormat/Wizard/NumberBase.php:58

        $this->locale = $this->validateLocale($locale);

        if (class_exists(NumberFormatter::class)) {
            $this->localeFormat = $this->getLocaleFormat();
        }
    }

    /**
     * Stub: should be implemented as a concrete method in concrete wizards.
     */
    abstract protected function getLocaleFormat(): string;

    /**
     * @throws Exception If the locale code is not a valid format
     */
    private function validateLocale(string $locale): string
    {
        if (preg_match(Locale::STRUCTURE, $locale, $matches, PREG_UNMATCHED_AS_NULL) !== 1) {
            throw new Exception("Invalid locale code '{$locale}'");
        }

        ['language' => $language, 'script' => $script, 'country' => $country] = $matches;
        // Set case and separator to match standardised locale case
        $language = strtolower($language);
        $script = ($script === null) ? null : ucfirst(strtolower($script));
        $country = ($country === null) ? null : strtoupper($country);

        $this->fullLocale = implode('-', array_filter([$language, $script, $country]));

        return $country === null ? $language : "{$language}-{$country}";
    }

    public function format(): string
    {
        return NumberFormat::FORMAT_GENERAL;
    }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Pass codes of the form 'll', 'll-CC' or 'll-Ssss-CC' ('fr', 'pt-BR', 'zh-Hans-CN')
2. Normalize input at your boundary against Locale::STRUCTURE or a whitelist before calling setLocale
3. Catch the exception and surface the bad value early to the caller/UI

Example fix

// before
$wizard->setLocale($userLocale); // 'english' -> throws

// after
if (preg_match(\PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Locale::STRUCTURE, $userLocale) === 1) {
    $wizard->setLocale($userLocale);
}

$structure = \PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Locale::STRUCTURE;
if (preg_match($structure, $userLocale) !== 1) {
    throw new InvalidArgumentException("Bad locale '$userLocale'");
}
$wizard->setLocale($userLocale);

function isValidWizardLocale(string $locale): bool
{
    return preg_match(
        \PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Locale::STRUCTURE,
        $locale
    ) === 1;
}

try {
    $wizard->setLocale($userLocale);
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    // log and continue with default (non-localized) format
}

When it happens

Trigger: Wizard setLocale('english'), setLocale('en-USA'), setLocale('zh_Hans_CN_POSIX') — any string not matching ^(ll)([-_]ssss)?([-_]cc)?$ shape.

Common situations: Pasting locale identifiers from other ecosystems (ISO-639-2 'eng', POSIX variants, BCP-47 extension subtags) into the wizard's setLocale(); passing user input unvalidated.

Related errors

• The Intl extension does not support Accounting Formats witho
• Unable to read locale data for '{$locale}'
• Invalid R1C1-format Cell Reference
• Invalid A1-format Cell Reference
• File doesn't seem to be an OLE container.

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/ec8830b64bed4caa. Report an issue: GitHub.