valyala/fasthttp · error

too big file: %d bytes

Error message

too big file: %d bytes

What it means

newFSFile rejects files whose size does not fit into an int (int(n) != int64(n)) because content-length and buffering are tracked as int. On 32-bit builds this fires for files larger than ~2 GiB; on 64-bit builds practically never.

Source

Thrown at fs.go:1937

		// On macOS the gzip seems to truncate the nanoseconds in the mod time causing the original file
		// to look newer than the gzipped file.
		if fileInfoOriginal.ModTime().Sub(fileInfo.ModTime()) >= time.Second {
			// The compressed file became stale. Re-create it.
			_ = f.Close()
			_ = os.Remove(filePath)
			return h.compressAndOpenFSFile(filePathOriginal, fileEncoding)
		}
	}

	return h.newFSFile(f, fileInfo, mustCompress, filePath, fileEncoding)
}

func (h *fsHandler) newFSFile(f fs.File, fileInfo fs.FileInfo, compressed bool, filePath, fileEncoding string) (*fsFile, error) {
	n := fileInfo.Size()
	contentLength := int(n)
	if n != int64(contentLength) {
		_ = f.Close()
		return nil, fmt.Errorf("too big file: %d bytes", n)
	}

	// detect content-type
	ext := fileExtension(fileInfo.Name(), compressed, h.compressedFileSuffixes[fileEncoding])
	contentType := mime.TypeByExtension(ext)
	if contentType == "" {
		data, err := readFileHeader(f, compressed, fileEncoding)
		if err != nil {
			return nil, fmt.Errorf("cannot read header of the file %q: %w", fileInfo.Name(), err)
		}
		contentType = http.DetectContentType(data)
	}

	lastModified := fileInfo.ModTime()
	ff := &fsFile{
		h:               h,
		f:               f,
		filename:        filePath,

View on GitHub (pinned to c96f600972)

Solutions

1. Build for a 64-bit platform (GOARCH=amd64/arm64)
2. Serve the big file via a different mechanism (e.g. http.ServeFile from net/http, or streaming manually)
3. Split or reduce the file below 2 GiB

Example fix

// before
GOOS=linux GOARCH=386 go build ./cmd/server
// after
GOOS=linux GOARCH=amd64 go build ./cmd/server

if fi, err := os.Stat(path); err == nil && fi.Size() > math.MaxInt32 { /* too big for 32-bit int; use another serving path */ }

if err := ctx.SendFile(bigPath); err != nil { if strings.HasPrefix(err.Error(), "too big file") { stream manually } }

When it happens

Trigger: Serving a file via FS/SendFile whose fs.FileInfo.Size() exceeds the platform int range — typically >2,147,483,647 bytes on a 32-bit (GOARCH=386/arm) binary.

Common situations: Hosting large videos/archives (>2GB) with fasthttp compiled for 32-bit platforms; embedded/arm devices serving big media.

Related errors

• directory with unexpected suffix found: %q: suffix: %q
• must implement seek
• must implement readat
• directory index required
• no 'create file' permissions

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/764b44404330294c. Report an issue: GitHub.