gofiber/fiber · error

unknown binding_source %q

Error message

unknown binding_source %q

What it means

Returned by getBindingPrecedence (bind.go:491) when a `binding_source` struct tag contains a source name that isn't in the recognized set {uri, body, query, header, cookie}. The parser trims whitespace and switches on the exact token; anything else (typo, case mismatch, unsupported source) is rejected and the error is cached for that struct type so subsequent binds fail fast.

Source

Thrown at bind.go:491

			for p := range parts {
				sourceName := strings.TrimSpace(p)
				if sourceName == "" {
					continue
				}
				var source bindSource
				switch sourceName {
				case "uri":
					source = sourceURI
				case "body":
					source = sourceBody
				case "query":
					source = sourceQuery
				case "header":
					source = sourceHeader
				case "cookie":
					source = sourceCookie
				default:
					err := fmt.Errorf("unknown binding_source %q", sourceName)
					bindingPrecedenceCache.Store(t, cachedPrecedence{err: err, sources: nil})
					return nil, err
				}

				// check for duplicates
				if !slices.Contains(precedence, source) {
					precedence = append(precedence, source)
				}
			}
		}
	}
	bindingPrecedenceCache.Store(t, cachedPrecedence{err: nil, sources: precedence})
	return precedence, nil
}

// All binds values from URI params, the request body, the query string,
// headers, and cookies into the provided struct in precedence order.
// Returns *BindError on parse failure (manual mode) or *Error with status 400 (auto-handling mode).

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Use only the allowed tokens: uri, body, query, header, cookie (lowercase, singular).
2. For JSON bodies use 'body' (the body binder handles the media type).
3. Add a unit test that binds a sample request per struct type so typos surface at test time, not in production.

Example fix

// before
type Req struct { Q string `binding_source:"params"` }

// after
type Req struct { Q string `binding_source:"query"` }

// Allowed binding_source tokens.
var allowedBindingSources = map[string]bool{
    "uri": true, "body": true, "query": true, "header": true, "cookie": true,
}

// In a test, reflect over struct tags and assert each binding_source token is allowed.

if err := c.Bind().All(&req); err != nil {
    if strings.Contains(err.Error(), "unknown binding_source") {
        // typo in a binding_source tag — fix the token
        return fiber.NewError(fiber.StatusBadRequest, "bad request schema")
    }
    return err
}

When it happens

Trigger: A tag like `binding_source:"params"`, `binding_source:"headers"` (plural), `binding_source:"form"`, or `binding_source:"URI"` (uppercase) — any token outside the five allowed lowercase names — on a struct passed to Bind().All().

Common situations: Typing a plural or synonyms (headers, params, form, path); using a case the switch doesn't match; attempting to bind a source Fiber doesn't expose (e.g. 'json' — body covers it).

Related errors

• multiple binding_source tags found on struct %s
• unsupported value type: %T
• binder: custom binder not found, please be sure to enter the
• log: context tag name and function are required
• logger: tag name and function are required

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