gofiber/fiber · error

fiber: keyauth unsupported error token

Error message

fiber: keyauth unsupported error token

What it means

The keyauth middleware validates the Config.Error field against the three RFC 6750 Bearer token error codes (invalid_request, invalid_token, insufficient_scope). Setting Error to any other string panics during configDefault() at middleware construction. The library enforces this so WWW-Authenticate challenge responses stay spec-compliant.

Source

Thrown at middleware/keyauth/config.go:136

	if cfg.Realm == "" {
		cfg.Realm = ConfigDefault.Realm
	}
	if cfg.SuccessHandler == nil {
		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, " ") {

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Set Config.Error to one of the package constants: keyauth.ErrorInvalidRequest, keyauth.ErrorInvalidToken, or keyauth.ErrorInsufficientScope.
2. If you need a custom error message, leave Error empty and instead customize Config.ErrorHandler to send your own response.
3. Double-check there are no typos or extra whitespace in the string value.

Example fix

// before
app.Use(keyauth.New(keyauth.Config{
    Validator:  validateKey,
    Error:      "forbidden",
}))
// after
app.Use(keyauth.New(keyauth.Config{
    Validator:  validateKey,
    Error:      keyauth.ErrorInvalidToken,
}))

validErrors := map[string]struct{}{
    keyauth.ErrorInvalidRequest:    {},
    keyauth.ErrorInvalidToken:      {},
    keyauth.ErrorInsufficientScope: {},
}
if cfg.Error != "" {
    if _, ok := validErrors[cfg.Error]; !ok {
        log.Fatalf("invalid keyauth Error %q", cfg.Error)
    }
}

When it happens

Trigger: Calling keyauth.New() with a Config whose Error field is set to a custom string like "forbidden" or "unauthorized" (or a typo like "invalid token" with a space). Any value not exactly equal to ErrorInvalidRequest, ErrorInvalidToken, or ErrorInsufficientScope triggers the panic.

Common situations: Developer copies an error code from documentation but mistypes it, or assumes free-form error strings are allowed. Migrating from a custom auth scheme and reusing internal error names that don't match RFC 6750. Copy-pasting between projects where constants differ.

Related errors

• fiber: keyauth error_description requires error
• 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/9582c4c437cfda3d.json. Report an issue: GitHub.