labstack/echo · error

echo key-auth middleware could not create extractors from Ke

Error message

echo key-auth middleware could not create extractors from KeyLookup string

What it means

Returned by KeyAuthConfig.ToMiddleware when createExtractors parsed the KeyLookup string without error but produced zero extractors. Each extractor reads the key from a source (header/query/form/cookie); having none means the middleware has nowhere to look. It is a defensive guard for malformed KeyLookup strings that the parser silently accepted.

Source

Thrown at middleware/key_auth.go:156

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
				}
				for _, key := range keys {
					valid, err := config.Validator(c, key, source)

View on GitHub (pinned to 05489dc173)

Solutions

1. Use a supported source prefix: "header:<name>", "header:<name>:<cut-prefix>", "query:<name>", "form:<name>", or "cookie:<name>".
2. For multiple sources use the comma form, e.g. "header:Authorization,header:X-Api-Key".
3. If unsure, omit KeyLookup entirely to use the default "header:Authorization:Bearer ".
4. Call config.ToMiddleware() to inspect the error instead of panicking.

Example fix

// before
m := middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    KeyLookup: "headers:X-Api-Key", // typo: 'headers' is not a valid source
    Validator: myValidator,
})
// after
m := middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    KeyLookup: "header:X-Api-Key",
    Validator: myValidator,
})

var validSources = map[string]bool{"header": true, "query": true, "form": true, "cookie": true}

func validKeyLookup(s string) bool {
    for _, part := range strings.Split(s, ",") {
        src, _, _ := strings.Cut(strings.TrimSpace(part), ":")
        if !validSources[src] { return false }
    }
    return true
}

When it happens

Trigger: Setting config.KeyLookup to a string that produces no usable extractor sources (e.g., a source prefix that is not header/query/form/cookie, or a degenerate comma-separated list). Note: an empty KeyLookup is replaced by the default, so you must explicitly pass a malformed string.

Common situations: Typos in the KeyLookup source prefix (e.g., "headers:Authorization" instead of "header:Authorization"), or hand-building a multi-source lookup string with a stray comma/empty segment.

Related errors

• echo key-auth middleware requires a validator function
• timeout must be set
• at least one AllowOrigins is required or UnsafeAllowOriginFu
• echo proxy middleware requires balancer
• echo rate limiter store configuration must be provided

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