AdguardTeam/AdGuardHome · warning

unknown language: %q

Error message

unknown language: %q

What it means

validateLang rejects a language string that is not in the allowed set of AdGuard Home UI languages. It is called on install-config checks, apply-config requests, language-change requests, and profile updates.

Source

Thrown at internal/home/i18n.go:60

	"sv",
	"th",
	"tr",
	"uk",
	"vi",
	"zh-cn",
	"zh-hk",
	"zh-tw",
)

// validateLang returns a standard error about if lang is an unknown language.
// If allowEmpty is true, the language can also be empty.
func validateLang(lang string, allowEmpty bool) (err error) {
	if allowEmpty && lang == "" {
		return nil
	}

	if !allowedLanguages.Has(lang) {
		return fmt.Errorf("unknown language: %q", lang)
	}

	return nil
}

// languageJSON is the JSON structure for language requests and responses.
type languageJSON struct {
	Language string `json:"language"`
}

// handleI18nCurrentLanguage is the handler for the GET
// /control/i18n/current_language HTTP API.
//
// TODO(d.kolyshev): Deprecated, remove it later.
func (web *webAPI) handleI18nCurrentLanguage(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
	l := web.logger

View on GitHub (pinned to b41aefbe51)

Solutions

1. Use an exact supported code (e.g. 'en', 'ru', 'zh-cn') — check the UI language dropdown for valid values
2. Don't send region-qualified locales; strip them before sending
3. Update to a newer build if the language was added after your binary was compiled

Example fix

// before
{"name":"admin","language":"en-US"}

// after
{"name":"admin","language":"en"}

var allowedLangs = slice.ToSet(locales)
if !allowedLangs.Has(req.Language) { req.Language = "en" }

func isValidLang(s string) bool { return allowedLanguages.Has(s) }

When it happens

Trigger: Sending a PUT to /control/profile/update, /control/i18n/update, or the install-config endpoints with a language field not in the compiled-in allowedLanguages set (e.g. 'jp' instead of 'ja', or a language not enabled in this build).

Common situations: Clients (mobile apps, third-party scripts) sending locale codes with region suffixes like 'en-US' or wrong ISO 639 codes; custom builds with a reduced set of translations.

Related errors

• networksetup failed to set dns servers: %w
• found no dns servers in %s
• writing conf: %w
• invalid pattern %q: %w
• creating watcher: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/8d140297a39bb8d8. Report an issue: GitHub.