labstack/echo · error

extractor source for lookup could not be split into needed p

Error message

extractor source for lookup could not be split into needed parts: %v

What it means

Returned by CreateExtractors / createExtractors (middleware/extractor.go:90-94) when a comma-separated lookup source has no ':' separator, so it cannot be split into <source>:<name>. Each source must have at least two parts; an unknown source name (e.g. a typo) silently produces no extractor but does NOT error — only the missing colon does.

Source

Thrown at middleware/extractor.go:93

	return createExtractors(lookups, limit)
}

func createExtractors(lookups string, limit uint) ([]ValuesExtractor, error) {
	if lookups == "" {
		return nil, nil
	}
	if limit == 0 {
		limit = 1
	} else if limit > extractorLimit {
		limit = extractorLimit
	}

	sources := strings.SplitSeq(lookups, ",")
	var extractors = make([]ValuesExtractor, 0)
	for source := range sources {
		parts := strings.Split(source, ":")
		if len(parts) < 2 {
			return nil, fmt.Errorf("extractor source for lookup could not be split into needed parts: %v", source)
		}

		switch parts[0] {
		case "query":
			extractors = append(extractors, valuesFromQuery(parts[1], limit))
		case "param":
			extractors = append(extractors, valuesFromParam(parts[1], limit))
		case "cookie":
			extractors = append(extractors, valuesFromCookie(parts[1], limit))
		case "form":
			extractors = append(extractors, valuesFromForm(parts[1], limit))
		case "header":
			prefix := ""
			if len(parts) > 2 {
				prefix = parts[2]
			}
			extractors = append(extractors, valuesFromHeader(parts[1], prefix, limit))
		}

View on GitHub (pinned to 05489dc173)

Solutions

1. Format every source as '<source>:<name>' (header:Authorization, query:token, param:id, cookie:session, form:field)
2. Drop trailing commas and empty segments
3. Build the lookup string from constants/validated parts rather than free text

Example fix

// before
_ = middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    KeyLookup: "Authorization",
})
// after
_ = middleware.KeyAuthWithConfig(middleware.KeyAuthConfig{
    KeyLookup: "header:Authorization",
})

func validLookup(s string) error {
    for _, src := range strings.Split(s, ",") {
        if strings.TrimSpace(src) == "" { continue }
        if len(strings.Split(src, ":")) < 2 {
            return fmt.Errorf("bad lookup source %q (want 'source:name')", src)
        }
    }
    return nil
}
if err := validLookup(cfg.KeyLookup); err != nil { return err }

ext, err := middleware.CreateExtractors(lookup, 1)
if err != nil {
    return fmt.Errorf("invalid extractor config %q: %w", lookup, err)
}

When it happens

Trigger: Passing "Authorization" (missing the 'header:' prefix), "header" (missing ':name'), or "header:Authorization,query" (second source lacks ':') to a middleware KeyAuth/JWT extractor `Lookup`/`TokenLookup` option.

Common situations: Configuring middleware KeyAuth, JWT, or RequestID with a custom lookup string and forgetting the 'source:name' format; trailing comma leaving an empty segment.

Related errors

• echo basic-auth middleware requires a validator function
• echo body-dump middleware requires a handler function
• invalid gzip level
• panic: err from config.ToMiddleware() in RequestLoggerWithCo
• ErrValidatorNotRegistered

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