gofiber/fiber · error

fiber: keyauth error_description requires error

Error message

fiber: keyauth error_description requires error

What it means

The keyauth Config.ErrorDescription field is a sub-parameter of the RFC 6750 WWW-Authenticate challenge and is only meaningful when paired with an Error code. Setting ErrorDescription while leaving Error empty is an inconsistent state that the library rejects at construction via a panic in configDefault().

Source

Thrown at middleware/keyauth/config.go:140

		cfg.SuccessHandler = ConfigDefault.SuccessHandler
	}
	if cfg.ErrorHandler == nil {
		cfg.ErrorHandler = ConfigDefault.ErrorHandler
	}

	if len(getAuthSchemes(cfg.Extractor)) == 0 && cfg.Challenge == "" {
		cfg.Challenge = fmt.Sprintf("ApiKey realm=%q", cfg.Realm)
	}

	if cfg.Error != "" {
		switch cfg.Error {
		case ErrorInvalidRequest, ErrorInvalidToken, ErrorInsufficientScope:
		default:
			panic("fiber: keyauth unsupported error token")
		}
	}
	if cfg.ErrorDescription != "" && cfg.Error == "" {
		panic("fiber: keyauth error_description requires error")
	}
	if cfg.ErrorURI != "" {
		if cfg.Error == "" {
			panic("fiber: keyauth error_uri requires error")
		}
		if u, err := url.Parse(cfg.ErrorURI); err != nil || !u.IsAbs() {
			panic("fiber: keyauth error_uri must be absolute")
		}
	}
	if cfg.Error == ErrorInsufficientScope {
		if cfg.Scope == "" {
			panic("fiber: keyauth insufficient_scope requires scope")
		}
		for scope := range strings.SplitSeq(cfg.Scope, " ") {
			if scope == "" || !isScopeToken(scope) {
				panic("fiber: keyauth scope contains invalid token")
			}
		}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Set Config.Error to a valid RFC 6750 code (invalid_request, invalid_token, or insufficient_scope) whenever you set ErrorDescription.
2. Remove the ErrorDescription value if you do not need the structured challenge parameters.
3. Validate the (Error, ErrorDescription) pairing in a helper before constructing the middleware.

Example fix

// before
app.Use(keyauth.New(keyauth.Config{
    Validator:        validateKey,
    ErrorDescription: "the token has expired",
}))
// after
app.Use(keyauth.New(keyauth.Config{
    Validator:        validateKey,
    Error:            keyauth.ErrorInvalidToken,
    ErrorDescription: "the token has expired",
}))

if cfg.ErrorDescription != "" && cfg.Error == "" {
    log.Fatal("keyauth: ErrorDescription requires Error to be set")
}

When it happens

Trigger: Calling keyauth.New() with Config.ErrorDescription set to a non-empty string but Config.Error left at its zero value (""). This commonly happens when a developer fills in the human-readable description but forgets the machine-readable error code.

Common situations: Porting a hand-built 401 response into keyauth config and only carrying over the descriptive text. Editing config incrementally and committing the description before the error code. Misreading docs that show ErrorDescription as standalone.

Related errors

• fiber: keyauth unsupported error token
• fiber: keyauth error_uri requires error
• fiber: keyauth error_uri must be absolute
• fiber: keyauth insufficient_scope requires scope
• fiber: keyauth scope contains invalid token

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