fiber: keyauth scope requires insufficient_scope error

Error message

fiber: keyauth scope requires insufficient_scope error

What it means

The keyauth Config.Scope field is only valid when Config.Error is ErrorInsufficientScope, because scope is an RFC 6750 parameter specific to that error. Setting Scope while Error is empty or set to a different code panics in configDefault().

Source

Thrown at middleware/keyauth/config.go:160

	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")
			}
		}
	} else if cfg.Scope != "" {
		panic("fiber: keyauth scope requires insufficient_scope error")
	}

	return cfg
}

func isScopeToken(s string) bool {
	for i := 0; i < len(s); i++ {
		c := s[i]
		if c < 0x21 || c > 0x7e || c == '"' || c == '\\' {
			return false
		}
	}
	return s != ""
}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

Set Config.Error to keyauth.ErrorInsufficientScope whenever you set Config.Scope.
If you only want to validate required scopes, implement that logic inside your Validator function instead of using the Scope field.
Remove Scope if you are not using the insufficient_scope challenge.

Example fix

// before
app.Use(keyauth.New(keyauth.Config{
    Validator: validateKey,
    Scope:     "read write",
}))
// after
app.Use(keyauth.New(keyauth.Config{
    Validator: validateKey,
    Error:     keyauth.ErrorInsufficientScope,
    Scope:     "read write",
}))

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Scope != "" && cfg.Error != keyauth.ErrorInsufficientScope {
    log.Fatal("keyauth: Scope is only valid when Error is insufficient_scope")
}

Prevention

Keep Scope and Error=insufficient_scope together in one config block.
Implement required-scope enforcement inside Validator rather than misusing the Scope field.

When it happens

Trigger: Calling keyauth.New() with Config.Scope populated but Config.Error unset, or Error set to invalid_request/invalid_token. The else-if branch at config.go:159 catches any non-empty Scope not paired with insufficient_scope.

Common situations: Developer adds the Scope field intending to declare required scopes but never switches Error to insufficient_scope. Leftover Scope from an earlier config revision. Misunderstanding that Scope is challenge metadata, not a general required-scopes list.

Related errors

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