gofiber/fiber · error · ErrFileStore

%w: %q to %q: %w

Error message

%w: %q to %q: %w

What it means

Returned by SaveFileToStorage when the Storage backend's SetWithContext call fails. Wraps ErrFileStore, the filename, the destination path, and the backend's error: 'file: failed to store file: "report.pdf" to "uploads/2024/report.pdf": <backend err>'. This is the final stage of the pipeline, after the body was read and size-checked successfully.

Source

Thrown at ctx.go:600

		return fmt.Errorf("%w: %q: %w", ErrFileRead, fileheader.Filename, fasthttp.ErrBodyTooLarge)
	}

	buf := bytebufferpool.Get()
	defer bytebufferpool.Put(buf)

	limitedReader := io.LimitReader(file, int64(maxUploadSize)+1)
	if _, err = buf.ReadFrom(limitedReader); err != nil {
		return fmt.Errorf("%w: %q: %w", ErrFileRead, fileheader.Filename, err)
	}

	if buf.Len() > maxUploadSize {
		return fmt.Errorf("%w: %q: %w", ErrFileRead, fileheader.Filename, fasthttp.ErrBodyTooLarge)
	}

	data := append([]byte(nil), buf.Bytes()...)

	if err := storage.SetWithContext(c.Context(), path, data, 0); err != nil {
		return fmt.Errorf("%w: %q to %q: %w", ErrFileStore, fileheader.Filename, path, err)
	}

	return nil
}

// Secure returns whether a secure connection was established.
func (c *DefaultCtx) Secure() bool {
	return c.Scheme() == schemeHTTPS
}

// Status sets the HTTP status for the response.
// This method is chainable.
func (c *DefaultCtx) Status(status int) Ctx {
	c.fasthttp.Response.SetStatusCode(status)
	return c
}

// String returns unique string representation of the ctx.

View on GitHub (pinned to a105acad6c)

Solutions

1. Unwrap and classify the backend error (errors.Is(err, fiber.ErrFileStore)) then retry idempotent writes or surface 502/503.
2. Verify storage connectivity and credentials out-of-band (a health check against the same Storage) before blaming upload code.
3. Make the route honor c.Context() cancellation; long uploads to slow storage can trip request deadlines.
4. Use a deterministic key so a retry after a transient failure overwrites safely rather than duplicating.

Example fix

if err := c.SaveFileToStorage(fh, key, store); err != nil {
    if errors.Is(err, fiber.ErrFileStore) {
        log.Errorf("storage write failed for %s: %v", key, err)
        return c.Status(fiber.StatusBadGateway).
            SendString("storage unavailable")
    }
    return err
}

// optional preflight: ping the storage backend before accepting uploads
if err := store.SetWithContext(ctx, "healthcheck", []byte("ok"), 0); err != nil {
    return fiber.NewError(fiber.StatusServiceUnavailable, "storage down")
}

null

if err := c.SaveFileToStorage(fh, key, store); err != nil {
    if errors.Is(err, fiber.ErrFileStore) {
        log.Errorf("storage write failed for %s: %v", key, err)
        return fiber.NewError(fiber.StatusBadGateway, "storage unavailable")
    }
    return err
}

When it happens

Trigger: Calling c.SaveFileToStorage(fh, path, storage) where storage.SetWithContext returns an error: S3/blob put failed (auth, bucket missing, network), Redis/MySQL write failed, context canceled (client closed the request), or a custom Storage implementation returned any non-nil error.

Common situations: Expired/rotated storage credentials, wrong bucket/endpoint configuration, network partition to the storage service, context cancellation on slow uploads, permission errors on the destination key, or a custom Storage with a bug.

Related errors

• %w: %q: %w
• file: failed to open file
• failed to listen: %w
• cache: failed to get key %q from storage: %w
• cache: failed to get raw key %q from storage: %w

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