gofiber/fiber · error · ErrNoHandlers

format: at least one handler is required, but none were set

Error message

format: at least one handler is required, but none were set

What it means

ErrNoHandlers (error.go:56) is returned by DefaultRes.Format (res.go:432) when c.Format() is called with zero ResFmt arguments. Format performs content negotiation by selecting among the provided handlers; with none there is nothing to negotiate, so it refuses rather than silently doing nothing.

Source

Thrown at error.go:56

	// ErrRangeUnsupported is returned for a Range header whose range unit is
	// not "bytes". RFC 9110 Section 14.2 requires an origin server to IGNORE
	// a Range header field with a range unit it does not understand, so
	// callers receiving this error should serve the full representation
	// instead of returning an error response. It still carries a
	// 400 Bad Request status as a safety net, so blind propagation does not
	// surface as a 500.
	ErrRangeUnsupported   = NewError(StatusBadRequest, "range: unsupported range unit")
	ErrRangeTooLarge      = NewError(StatusRequestedRangeNotSatisfiable, "range: too many ranges")
	ErrRangeUnsatisfiable = errors.New("range: unsatisfiable range")
)

// Binder errors
var ErrCustomBinderNotFound = errors.New("binder: custom binder not found, please be sure to enter the right name")

// Format errors
var (
	// ErrNoHandlers is returned when c.Format is called with no arguments.
	ErrNoHandlers = errors.New("format: at least one handler is required, but none were set")
)

// gofiber/schema errors
type (
	// ConversionError Conversion error exposes the internal schema.ConversionError for public use.
	ConversionError = schema.ConversionError
	// UnknownKeyError error exposes the internal schema.UnknownKeyError for public use.
	UnknownKeyError = schema.UnknownKeyError
	// EmptyFieldError error exposes the internal schema.EmptyFieldError for public use.
	EmptyFieldError = schema.EmptyFieldError
	// MultiError error exposes the internal schema.MultiError for public use.
	MultiError = schema.MultiError
)

// encoding/json errors
type (
	// InvalidUnmarshalError describes an invalid argument passed to Unmarshal.
	// (The argument to Unmarshal must be a non-nil pointer.)

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Always pass at least one ResFmt, e.g. c.Format(fiber.ResFmt{MediaType: "application/json", Handler: writeJSON}).
2. When building the slice dynamically, fall back to a default handler if the list is empty.
3. Guard the call site: if len(handlers) == 0 return your own error before calling Format.

Example fix

// before
c.Format() // no handlers

// after
c.Format(
    fiber.ResFmt{MediaType: "application/json", Handler: func(c fiber.Ctx) error { return c.JSON(data) }},
    fiber.ResFmt{MediaType: "text/html", Handler: func(c fiber.Ctx) error { return c.SendString(html) }},
)

// Ensure at least one handler before calling Format.
if len(handlers) == 0 {
    handlers = []fiber.ResFmt{{MediaType: "default", Handler: writeDefault}}
}
c.Format(handlers...)

if err := c.Format(handlers...); err != nil {
    if errors.Is(err, fiber.ErrNoHandlers) {
        return fiber.NewError(fiber.StatusInternalServerError, "no format handlers configured")
    }
    return err
}

When it happens

Trigger: Calling c.Format() with no arguments, or passing a variadic slice that is nil/empty, e.g. c.Format(handlers...) where handlers was never populated. Also when a builder assembles the handler list conditionally and the list ends up empty.

Common situations: Building content-negotiation handlers from configuration that yields none, or copy-pasting a Format call and forgetting to add the handlers.

Related errors

• format handler is nil for media type %q at index %d
• min constraint requires an argument
• max constraint requires an argument
• range constraint requires two arguments
• regex constraint requires a pattern argument

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