labstack/echo · error

echo key-auth middleware could not create key extractor: %w

Error message

echo key-auth middleware could not create key extractor: %w

What it means

Returned by KeyAuthConfig.ToMiddleware() when createExtractors() fails to parse the config.KeyLookup string. The lookup string must follow the 'source:name' format (e.g. 'header:Authorization', 'query:token', 'cookie:session', 'form:key', 'param:id') optionally comma-separated for multiple sources. If a segment cannot be split into at least two colon-delimited parts, or uses an unknown source prefix, the error wraps that failure.

Source

Thrown at middleware/key_auth.go:153

}

// ToMiddleware converts KeyAuthConfig to middleware or returns an error for invalid configuration
func (config KeyAuthConfig) ToMiddleware() (echo.MiddlewareFunc, error) {
	if config.Skipper == nil {
		config.Skipper = DefaultKeyAuthConfig.Skipper
	}
	if config.KeyLookup == "" {
		config.KeyLookup = DefaultKeyAuthConfig.KeyLookup
	}
	if config.Validator == nil {
		return nil, errors.New("echo key-auth middleware requires a validator function")
	}

	limit := cmp.Or(config.AllowedCheckLimit, 1)

	extractors, cErr := createExtractors(config.KeyLookup, limit)
	if cErr != nil {
		return nil, fmt.Errorf("echo key-auth middleware could not create key extractor: %w", cErr)
	}
	if len(extractors) == 0 {
		return nil, errors.New("echo key-auth middleware could not create extractors from KeyLookup string")
	}

	return func(next echo.HandlerFunc) echo.HandlerFunc {
		return func(c *echo.Context) error {
			if config.Skipper(c) {
				return next(c)
			}

			var lastExtractorErr error
			var lastValidatorErr error
			for _, extractor := range extractors {
				keys, source, extrErr := extractor(c)
				if extrErr != nil {
					lastExtractorErr = extrErr
					continue

View on GitHub (pinned to 05489dc173)

Solutions

1. Set KeyLookup to a valid 'source:name' pair, e.g. 'header:Authorization' or 'query:api-key'.
2. For multiple extraction sources, comma-separate valid pairs, e.g. 'header:X-API-Key,query:key'.
3. Leave KeyLookup empty to use the default 'header:Authorization' (with 'Bearer ' optional prefix).
4. Remove trailing commas or empty segments from the lookup string.

Example fix

// before
middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    Validator:    fn,
    KeyLookup:    "Authorization", // missing source prefix
})
// after
middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    Validator:    fn,
    KeyLookup:    "header:Authorization",
})

// Validate KeyLookup before building the middleware.
func validKeyLookup(s string) error {
    if s == "" {
        return nil // default applies
    }
    for _, src := range strings.Split(s, ",") {
        parts := strings.Split(src, ":")
        if len(parts) < 2 {
            return fmt.Errorf("invalid KeyLookup segment %q: need 'source:name'", src)
        }
        switch parts[0] {
        case "query", "param", "cookie", "form", "header":
        default:
            return fmt.Errorf("invalid KeyLookup source %q in %q", parts[0], src)
        }
    }
    return nil
}

// usage
if err := validKeyLookup(cfg.KeyLookup); err != nil { return err }

When it happens

Trigger: Calling middleware.KeyAuthWithConfig (or KeyAuth) with a KeyLookup value like 'Authorization' (missing source prefix), 'header' (missing name), 'foo:bar' (unknown source 'foo'), or an empty segment from a trailing comma. The error surfaces during middleware construction, not at request time.

Common situations: Typos in the KeyLookup string; copying a header name without the 'header:' prefix; leaving a dangling comma in a multi-source lookup; migrating from another framework that uses a different lookup syntax.

Related errors

• echo key-auth middleware requires a validator function
• echo key-auth middleware could not create extractors from Ke
• timeout must be set
• at least one AllowOrigins is required or UnsafeAllowOriginFu
• echo proxy middleware requires balancer

AI-assisted analysis of labstack/echo@05489dc173 (2026-08-04). Data as JSON: /data/errors/7287e5312314627c.json. Report an issue: GitHub.