{"id":"aa0e060b513773da","repo":"gofiber/fiber","slug":"basicauth-charset-must-be-utf-8","errorCode":null,"errorMessage":"basicauth: charset must be UTF-8","messagePattern":"basicauth: charset must be UTF-8","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"middleware/basicauth/config.go","lineNumber":145,"sourceCode":"\tif cfg.Next == nil {\n\t\tcfg.Next = ConfigDefault.Next\n\t}\n\n\tif cfg.Users == nil {\n\t\tcfg.Users = ConfigDefault.Users\n\t}\n\n\tif cfg.Realm == \"\" {\n\t\tcfg.Realm = ConfigDefault.Realm\n\t}\n\n\tswitch {\n\tcase cfg.Charset == \"\":\n\t\tcfg.Charset = ConfigDefault.Charset\n\tcase utils.EqualFold(cfg.Charset, \"UTF-8\"):\n\t\tcfg.Charset = \"UTF-8\"\n\tdefault:\n\t\tpanic(\"basicauth: charset must be UTF-8\")\n\t}\n\n\tif cfg.HeaderLimit <= 0 {\n\t\tcfg.HeaderLimit = ConfigDefault.HeaderLimit\n\t}\n\n\tif cfg.Authorizer == nil {\n\t\tverifiers, dummyVerify, err := buildVerifiers(cfg.Users)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tcfg.Authorizer = func(user, pass string, _ fiber.Ctx) bool {\n\t\t\tverify, ok := verifiers[user]\n\t\t\tif !ok {\n\t\t\t\tverify = dummyVerify\n\t\t\t}\n\t\t\tres := verify(pass)\n\t\t\treturn ok && res","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/middleware/basicauth/config.go#L127-L163","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Set Charset to \"UTF-8\" (any case) or omit it entirely to accept the ConfigDefault.","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\".","Search your config for the literal value you passed and replace it with \"UTF-8\"."],"exampleFix":"// before\nbasicauth.New(basicauth.Config{Users: users, Charset: \"ISO-8859-1\"})\n\n// after\nbasicauth.New(basicauth.Config{Users: users, Charset: \"UTF-8\"}) // or omit Charset","handlingStrategy":"validation","validationCode":"func validateBasicAuthCharset(c basicauth.Config) error {\n    if c.Charset == \"\" { return nil } // default is UTF-8\n    if !utils.EqualFold(c.Charset, \"UTF-8\") {\n        return fmt.Errorf(\"basicauth Charset %q is not allowed; only UTF-8 is permitted\", c.Charset)\n    }\n    return nil\n}\n\nif err := validateBasicAuthCharset(cfg); err != nil { log.Fatal(err) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat Charset as a fixed \"UTF-8\" constant; never expose it as a user-tunable setting.","If migrating from a Latin-1 system, decode passwords to UTF-8 in a custom Authorizer instead of changing Charset."],"tags":["basicauth","authentication","config","charset","rfc-7617","panic"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}