gofiber/fiber · warning · ErrRangeUnsatisfiable

range: unsatisfiable range

Error message

range: unsatisfiable range

What it means

ErrRangeUnsatisfiable (error.go:47) is the sentinel for an HTTP Range request whose byte ranges cannot be satisfied against the current resource (e.g. a start position past the end of the content, or a reversed range). Unlike the 400-carrying ErrRangeMalformed, this is a pure plain error (no embedded status) intended for the 416 Requested Range Not Satisfiable response path, distinct from malformed-syntax (400) cases.

Source

Thrown at error.go:47

	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 9a4c7e57fe)

Solutions

1. Respond with 416 Range Not Satisfiable and a Content-Range header showing the actual total length.
2. If full-content fallback is acceptable, ignore the Range header and serve the complete representation.
3. Validate that the requested start is within content bounds before applying the range.

Example fix

// before
if err := c.SendFile("report.pdf"); err != nil {
    return err // surfaces ErrRangeUnsatisfiable to the default error handler
}

// after
if err := c.SendFile("report.pdf"); err != nil {
    if errors.Is(err, fiber.ErrRangeUnsatisfiable) {
        return c.Status(fiber.StatusRequestedRangeNotSatisfiable).
            Set("Content-Range", "bytes */"+strconv.Itoa(size)).SendString("range not satisfiable")
    }
    return err
}

// Optionally fall back to full content when a range is unsatisfiable.
// (Validation is at response time; pre-check start against known size.)
if r := c.Get(fiber.HeaderRange); r != "" {
    if start, _ := parseRangeStart(r); start >= contentSize {
        c.Response().Header.Del(fiber.HeaderAcceptRanges)
    }
}

if err := c.SendFile(path); err != nil {
    if errors.Is(err, fiber.ErrRangeUnsatisfiable) {
        return c.Status(fiber.StatusRequestedRangeNotSatisfiable).
            Set("Content-Range", fmt.Sprintf("bytes */%d", size)).
            SendString("range not satisfiable")
    }
    return err
}

When it happens

Trigger: A client sends 'Range: bytes=1000-2000' for a 500-byte body, or 'bytes=10-5' (reversed), or a suffix/last-byte start beyond content length. The Range parser produces an unsatisfiable result and the handler returns this error to drive a 416 response.

Common situations: Clients (download managers, media players) computing ranges from stale Content-Length, proxies rewriting ranges incorrectly, or handlers serving variable-length content where the client's cached length is wrong.

Related errors

• min constraint requires an argument
• max constraint requires an argument
• range constraint requires two arguments
• regex constraint requires a pattern argument
• shutdown: graceful timeout has been reached, exiting

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