juicedata/juicefs · warning

space not enough on device

Error message

space not enough on device

What it means

errStageFull signals that the staging directory's device has run out of space (or is at its configured staging limit), so a new cache block cannot be staged on disk and the block is uploaded directly to object storage instead. It is returned by the disk cache's stagePath path when stageFull is set or free space checks fail.

Source

Thrown at pkg/chunk/disk_cache.go:47

	"strconv"
	"strings"
	"sync"
	"sync/atomic"
	"syscall"
	"time"

	"github.com/charlievieth/fastwalk"
	"github.com/dustin/go-humanize"
	"github.com/google/uuid"
	"github.com/juicedata/juicefs/pkg/utils"
)

var (
	stagingDir          = "rawstaging"
	cacheDir            = "raw"
	maxIODur            = time.Second * 30
	stagingBlocks       atomic.Int64
	errStageFull        = errors.New("space not enough on device")
	errStageConcurrency = errors.New("concurrent staging limit reached")
)

type cacheKey struct {
	id   uint64
	indx uint32
	size uint32
}

func (k cacheKey) String() string { return fmt.Sprintf("%d_%d_%d", k.id, k.indx, k.size) }

type pendingFile struct {
	key       string
	page      *Page
	dropCache bool
}

type diskCache struct {

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Free space on the device backing the cache/staging directory or point --cache-dir to a larger volume.
  2. Lower the staging pressure by reducing --max-staging-write-hours or increasing --free-space disk ratio so staging evicts earlier.
  3. Ensure writeback uploaders can keep up (increase upload bandwidth/limits) so staged blocks drain; the client falls back to direct upload in the meantime.
Defensive patterns

Strategy: fallback

Validate before calling

// before mounting, check cache device free space
st, _ := os.Statvfs(cacheDir) // or syscall.Statfs
if float64(st.Bavail)*float64(st.Bsize) < minFreeBytes { /* enlarge or clean disk */ }

Try / catch

path, err := cache.Stage(key, data)
if errors.Is(err, chunk.ErrStageFull) {
	logger.Warnf("staging full, uploading %s directly", key)
	return uploadDirect(key, data)
}

Prevention

When it happens

Trigger: Calling the disk-cache staging write path (cache.stage -> stagePath) when cache.stageFull is true, i.e. after the staging device failed a free-space/min-free-ratio check.

Common situations: The disk holding the cache dir (rawstaging) fills up during heavy random-read workloads; writeback mode enabled with a small or nearly full cache volume.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/0157202e6a6cf880. Report an issue: GitHub.