What causes "basicauth: charset must be UTF-8" in gofiber/fiber?

Set Config.Charset to "" (let it default to UTF-8) or exactly "UTF-8".

basicauth: charset must be UTF-8

Error message

basicauth: charset must be UTF-8

What it means

The basicauth middleware only allows UTF-8 (case-insensitively) as the WWW-Authenticate realm charset; an explicit non-empty Charset that is not UTF-8 is rejected because Basic auth credentials are bytes decoded per the realm charset and any other value would corrupt or misrepresent credential handling. Empty Charset defaults to UTF-8 (ConfigDefault.Charset).

Solutions

Set Config.Charset to "" (let it default to UTF-8) or exactly "UTF-8".
Trim and case-normalize any externally-supplied charset value before assigning it: strings.TrimSpace(strings.ToUpper(v)) == "UTF-8".
Remove the Charset field entirely from your Config literal.

Example fix

// before
basicauth.New(basicauth.Config{ Charset: "ISO-8859-1" })
// after
basicauth.New(basicauth.Config{ /* Charset omitted; defaults to UTF-8 */ })

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Charset != "" && !utils.EqualFold(cfg.Charset, "UTF-8") {
    return fmt.Errorf("basicauth charset must be UTF-8, got %q", cfg.Charset)
}
// or simply normalize:
if cfg.Charset == "" || utils.EqualFold(cfg.Charset, "UTF-8") {
    cfg.Charset = "UTF-8"
} else {
    return fmt.Errorf("unsupported charset %q", cfg.Charset)
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        log.Fatalf("basicauth config invalid: %v", r)
    }
}()
basicauth.New(cfg)

Prevention

Omit Charset from basicauth.Config entirely; it defaults to UTF-8.
When loading Charset from env/config, trim whitespace and reject anything that is not case-insensitive 'UTF-8'.
Avoid trailing spaces/typos like "UTF8 " or "utf-8 \n" — they are not trimmed and will panic.

When it happens

Trigger: Calling basicauth.New(basicauth.Config{ Charset: "ISO-8859-1" }) (or "utf8", "ascii", "UTF-16", any non-empty non-UTF-8 value). Empty string and case variants of "UTF-8" are accepted/normalized.

Common situations: Copy-pasting a config from an old example that used Latin-1; setting Charset based on an environment variable that resolves to a different encoding name; typo like "UTF8 " (trailing space) — note this is NOT trimmed and will panic because utils.EqualFold("UTF8 ", "UTF-8") is false.

Related errors

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/aa0e060b513773da. Report an issue: GitHub.

Appendix: source

Thrown at middleware/basicauth/config.go:145

	if cfg.Next == nil {
		cfg.Next = ConfigDefault.Next
	}

	if cfg.Users == nil {
		cfg.Users = ConfigDefault.Users
	}

	if cfg.Realm == "" {
		cfg.Realm = ConfigDefault.Realm
	}

	switch {
	case cfg.Charset == "":
		cfg.Charset = ConfigDefault.Charset
	case utils.EqualFold(cfg.Charset, "UTF-8"):
		cfg.Charset = "UTF-8"
	default:
		panic("basicauth: charset must be UTF-8")
	}

	if cfg.HeaderLimit <= 0 {
		cfg.HeaderLimit = ConfigDefault.HeaderLimit
	}

	if cfg.Authorizer == nil {
		verifiers, dummyVerify, err := buildVerifiers(cfg.Users)
		if err != nil {
			panic(err)
		}
		cfg.Authorizer = func(user, pass string, _ fiber.Ctx) bool {
			verify, ok := verifiers[user]
			if !ok {
				verify = dummyVerify
			}
			res := verify(pass)
			return ok && res

View on GitHub (pinned to a105acad6c)