gofiber/fiber · error

unknown binding_source

Error message

unknown binding_source %q

What it means

The `binding_source` tag accepts only: uri, body, query, header, cookie. Any other token (e.g., form, path, params) makes getBindingPrecedence return fmt.Errorf("unknown binding_source %q", sourceName). Like [76], the failure is cached in bindingPrecedenceCache.

Solutions

1. Use only the supported tokens: uri, body, query, header, cookie.
2. For form bodies, use `body` with the appropriate Content-Type.
3. Double-check spelling against the switch statement in getBindingPrecedence.

Example fix

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

// after
type Req struct {
    Q string `query:"q"`        // or use `binding_source:"query"` if custom precedence is required
}

allowed := map[string]bool{"uri": true, "body": true, "query": true, "header": true, "cookie": true}
for _, src := range strings.Split(tag, ",") {
    if !allowed[strings.TrimSpace(src)] { return fmt.Errorf("bad binding_source %q", src) }
}

func isValidBindingSource(tag string) bool {
    allowed := map[string]bool{"uri": true, "body": true, "query": true, "header": true, "cookie": true}
    for _, s := range strings.Split(tag, ",") {
        if !allowed[strings.TrimSpace(s)] { return false }
    }
    return true
}

When it happens

Trigger: Annotating a field with a binding_source value outside the allowed set, e.g., `binding_source:"form"` or `binding_source:"path"`.

Common situations: Misspelling a source name; assuming a source exists that doesn't (form, path); using values from an older/different library.

Related errors

• multiple binding_source tags found on struct
• basicauth: charset must be UTF-8
• binder: custom binder not found, please be sure to enter…
• [CORS] Invalid origin format in configuration:
• [CSRF] Invalid origin format in configuration:

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/1ce9b6c00bda9b47. Report an issue: GitHub.

Appendix: source

Thrown at bind.go:484

			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 a105acad6c)