What causes "locales not found in map" in kataras/iris?

Ensure the languages passed to New/i18n initialization exactly match (or are parent tags of) the LangMap keys.

locales not found in map

Error message

locales not found in map

What it means

The KV loader (i18n.KV) builds a Catalog from a LangMap and requires at least one locale to be successfully stored. If cat.Locales is empty after storing, it returns "locales not found in map". This happens when none of the languages in the map matched the languages registered in the Matcher (New's language arguments).

Source

Thrown at i18n/loader.go:131

			return nil, err
		}

		for _, langIndex := range languageIndexes {
			if langIndex == -1 {
				// If loader has more languages than defined for use in New function,
				// e.g. when New(KV(m), "en-US") contains el-GR and en-US but only "en-US" passed.
				continue
			}

			kv := keyValuesMulti[langIndex]
			err := cat.Store(langIndex, kv)
			if err != nil {
				return nil, err
			}
		}

		if n := len(cat.Locales); n == 0 {
			return nil, fmt.Errorf("locales not found in map")
		} else if options.Strict && n < len(m.Languages) {
			return nil, fmt.Errorf("locales expected to be %d but %d parsed", len(m.Languages), n)
		}

		return cat, nil
	}
}

// DefaultLoaderConfig represents the default loader configuration.
var DefaultLoaderConfig = LoaderConfig{
	Left:               "{{",
	Right:              "}}",
	Strict:             false,
	DefaultMessageFunc: nil,
	PluralFormDecoder:  internal.DefaultPluralFormDecoder,
	Funcs:              nil,
}

View on GitHub (pinned to 7bedaf55a0)

Solutions

Ensure the languages passed to New/i18n initialization exactly match (or are parent tags of) the LangMap keys.
Normalize language tags: use the same form in both places (e.g. "en-US" vs "en").
Log/verify which languages the Matcher registered before loading.
Remove Strict=false assumptions — this error fires regardless of Strict when zero locales parse.

Example fix

// before
app := iris.New()
app.I18n.Load(i18n.KV(i18n.LangMap{"en-US": {...}})) // no languages registered
// after
app.I18n.Load(i18n.KV(i18n.LangMap{"en-US": {...}}), "en-US")

Defensive patterns

Strategy: validation

Validate before calling

// verify map keys match registered languages before loading
for lang := range langMap {
    t := language.Make(lang)
    if t.String() == "und" {
        return fmt.Errorf("unparseable language tag in map: %q", lang)
    }
    log.Printf("locale %s -> %s", lang, t)
}
if len(langMap) == 0 {
    return fmt.Errorf("langMap is empty")
}

Try / catch

localizer, err := i18n.KV(langMap)(matcher)
if err != nil && strings.Contains(err.Error(), "locales not found in map") {
    return fmt.Errorf("no languages in map matched registered languages %v: %w", registered, err)
}

Prevention

Pass the exact same language tags to New that you use as map keys.
Keep one canonical spelling per locale (e.g. always "en-US").
Log matched/unmatched languages during load.
Add a startup assertion that at least one locale loaded.

When it happens

Trigger: Calling iris.New(i18n.KV(langMap), "en-US") (or app.I18n.Load with KV) where parseLanguageName returns -1 for every language in the map — i.e. the map's language keys don't match any of the languages passed to New/I18n initialization.

Common situations: Language key mismatches: map has "en" but New registered "en-US" (or vice versa), misspelled tags, or using subtags/newLoaderConfig where only a subset of languages was declared.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/86be71797e50b910. Report an issue: GitHub.