gofiber/fiber · warning

range: unsatisfiable range

Error message

range: unsatisfiable range

What it means

ErrRangeUnsatisfiable is a public sentinel at error.go:52 intended to represent an HTTP Range request whose selected byte ranges cannot be satisfied (the 416 condition). In this fiber/v3 checkout it has no internal callers: the Range parser in DefaultCtx.Range returns its siblings (ErrRangeMalformed, ErrRangeUnsupported, ErrRangeTooLarge) but not this one. It exists as a stable value for callers to return or match against.

Solutions

1. When serving ranged content yourself, compute the size and return ErrRangeUnsatisfiable (with a 416 response) when no range intersects the body.
2. Use the typed sibling errors (ErrRangeMalformed, ErrRangeUnsupported) for the corresponding parse failures so blind propagation does not surface as 500.
3. Match with errors.Is(err, fiber.ErrRangeUnsatisfiable) rather than string comparison so future revisions stay compatible.

Example fix

// before
if start >= size {
    return c.Status(fiber.StatusRequestedRangeNotSatisfiable).SendString("unsatisfiable")
}
// after
if start >= size {
    return fiber.ErrRangeUnsatisfiable
}

// isRangeUnsatisfiable reports whether err signals a 416 condition.
func isRangeUnsatisfiable(err error) bool {
    return errors.Is(err, fiber.ErrRangeUnsatisfiable)
}

ranges, err := c.Range(size)
if err != nil {
    if isRangeUnsatisfiable(err) {
        return c.Status(fiber.StatusRequestedRangeNotSatisfiable).SendString("unsatisfiable")
    }
    return err
}

When it happens

Trigger: A Range: bytes= header whose start offset equals or exceeds the representation size would conventionally map to this sentinel. In the current revision callers see no error from fiber itself; application code that performs its own Range validation must return ErrRangeUnsatisfiable explicitly, and consumers match it with errors.Is.

Common situations: Custom static-file or streaming handlers that parse Range headers and need a typed sentinel; version drift where a future revision returns this from DefaultCtx.Range; clients requesting bytes=1000- against a 500-byte body.

Related errors

• add: invalid http method
• binder: suitable content not found to parse body
• client: HTTPS to HTTP redirect blocked
• failed to dump request
• failed to read response

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

Appendix: source

Thrown at error.go:52

	ErrRedirectBackNoFallback = NewError(StatusInternalServerError, "Referer not found, you have to enter fallback URL for redirection.")
)

// Range errors
var (
	// ErrRangeMalformed is returned for a syntactically invalid Range header,
	// which RFC 9110 Section 14.2 allows a server to reject; it carries a
	// 400 Bad Request status so propagating it does not surface as a 500.
	ErrRangeMalformed = NewError(StatusBadRequest, "range: malformed range header string")
	// 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.

View on GitHub (pinned to a105acad6c)