binder: map destination is nil and cannot be initialized

Error message

binder: map destination is nil and cannot be initialized

What it means

Returned by parseToMap (binder/mapping.go:144) when the destination is a nil map whose reflect.Value cannot be Set. The binder wants to initialize the map with reflect.MakeMap, but if the caller passed the map by value (not through a pointer) the value is not addressable and cannot be mutated.

Solutions

Pass a pointer to the map: c.Bind().Query(&m) so reflect can allocate and assign the map.
Pre-initialize the map with make so the nil check is bypassed: m := make(map[string]string) before binding.
Ensure the destination is obtained via reflect.ValueOf(out).Elem() from a pointer (the normal Bind path does this; the error typically comes from direct parseToMap use).

Example fix

// before
var m map[string]string
c.Bind().Query(m) // or parseToMap(reflect.ValueOf(m), data) -> ErrMapNilDestination

// after
var m map[string]string
c.Bind().Query(&m) // pointer lets the binder allocate the map

Defensive patterns

Strategy: validation

Validate before calling

// Ensure maps are passed by pointer and/or pre-allocated
func prepareMapDest[T any]() (*map[string]string, error) {
    m := make(map[string]string)
    return &m, nil
}

Type guard

func isSettableMapPtr(v any) bool {
    rv := reflect.ValueOf(v)
    return rv.Kind() == reflect.Ptr && rv.Elem().Kind() == reflect.Map
}

Try / catch

if err := c.Bind().Query(&m); err != nil {
    if errors.Is(err, binder.ErrMapNilDestination) {
        m = make(map[string]string) // pre-allocate and retry
        err = c.Bind().Query(&m)
    }
    if err != nil { return err }
}

Prevention

Always pass a pointer to the destination: &m, not m.
Pre-allocate maps with make so the nil path is never hit.
Use the public Bind.* methods rather than calling parseToMap directly.

When it happens

Trigger: Passing a nil map directly rather than a pointer to a map: parseToMap(reflect.ValueOf(make-nil-map), data) where the Value was obtained from a non-pointer. Also when binding into a map field behind an interface that is not settable.

Common situations: Calling c.Bind().Query(m) with `var m map[string]string` (value, not pointer) — Go passes the map by value, reflect sees it as unsettable; binding into a nil map stored in an interface{} variable.

Related errors

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

Appendix: source

Thrown at binder/binder.go:21

import (
	"errors"
	"sync"
)

const (
	bindingURI        = "uri"
	bindingForm       = "form"
	bindingQuery      = "query"
	bindingHeader     = "header"
	bindingRespHeader = "respHeader"
	bindingCookie     = "cookie"
)

// Binder errors
var (
	ErrSuitableContentNotFound = errors.New("binder: suitable content not found to parse body")
	ErrMapNotConvertible       = errors.New("binder: map is not convertible to map[string]string or map[string][]string")
	ErrMapNilDestination       = errors.New("binder: map destination is nil and cannot be initialized")
	ErrInvalidDestinationValue = errors.New("binder: invalid destination value")
	ErrUnmatchedBrackets       = errors.New("unmatched brackets")
)

var errPoolTypeAssertion = errors.New("failed to type-assert to T")

var HeaderBinderPool = sync.Pool{
	New: func() any {
		return &HeaderBinding{}
	},
}

var RespHeaderBinderPool = sync.Pool{
	New: func() any {
		return &RespHeaderBinding{}
	},
}

View on GitHub (pinned to a105acad6c)