gofiber/fiber · critical

basicauth: charset must be UTF-8

Error message

basicauth: charset must be UTF-8

What it means

The basicauth middleware only permits the charset value "UTF-8" in the WWW-Authenticate header, per RFC 7617 which is the only charset browsers honor for Basic auth credential encoding. In configDefault (config.go:139-146) the Charset field is matched case-insensitively against "UTF-8"; anything else panics at startup because silently serving a non-UTF-8 realm would break credential parsing in browsers.

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 9a4c7e57fe)

Solutions

1. Set Charset to "UTF-8" (any case) or omit it entirely to accept the ConfigDefault.
2. If you genuinely need legacy Latin-1 credentials, implement a custom Authorizer that decodes passwords from Latin-1 before comparing, and keep Charset as "UTF-8".
3. Search your config for the literal value you passed and replace it with "UTF-8".

Example fix

// before
basicauth.New(basicauth.Config{Users: users, Charset: "ISO-8859-1"})

// after
basicauth.New(basicauth.Config{Users: users, Charset: "UTF-8"}) // or omit Charset

func validateBasicAuthCharset(c basicauth.Config) error {
    if c.Charset == "" { return nil } // default is UTF-8
    if !utils.EqualFold(c.Charset, "UTF-8") {
        return fmt.Errorf("basicauth Charset %q is not allowed; only UTF-8 is permitted", c.Charset)
    }
    return nil
}

if err := validateBasicAuthCharset(cfg); err != nil { log.Fatal(err) }

When it happens

Trigger: Calling basicauth.New(Config{Charset: "ISO-8859-1"}) or any value other than "UTF-8"/"utf-8"/"" . The empty string falls through to the ConfigDefault ("UTF-8"), so only an explicit non-UTF-8 value triggers the panic.

Common situations: Copying a charset from an older Basic auth implementation (e.g. a Java/Tomcat or legacy Nginx config that advertised Latin-1), or mistyping "UTF8" without the hyphen (which still fails — it must be exactly "UTF-8" modulo case).

Related errors

• decode SHA512 password: %w
• decode SHA256 password: %w
• fiber: keyauth middleware requires a validator function
• decode SHA256 password: invalid length
• favicon: file size exceeds max bytes %d

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/aa0e060b513773da.json. Report an issue: GitHub.