What causes "concurrent staging limit reached" in juicedata/juicefs?

Increase --max-staging-write-hours to allow more concurrent staged blocks.

concurrent staging limit reached

Error message

concurrent staging limit reached

What it means

errStageConcurrency indicates the number of blocks currently being staged has reached the configured max staging-write concurrency (maxStageWrite), so additional staging writes are rejected. Callers treat it specially: unlike other staging errors it is not counted as a stage failure or logged as a warning; the block is simply uploaded directly.

Source

Thrown at pkg/chunk/disk_cache.go:48

	"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 {
	id         string

View on GitHub (pinned to c9a67b23e8)

Solutions

Increase --max-staging-write-hours to allow more concurrent staged blocks.
If immediate direct upload is acceptable, no action needed: this is a soft backpressure signal, not a data loss condition.
Reduce writer concurrency or spread writes across more clients to stay under the staging limit.

Example fix

// before
juicefs mount --writeback --max-staging-write-hours 1 ... 
// after
juicefs mount --writeback --max-staging-write-hours 8 ...

Defensive patterns

Strategy: fallback

Try / catch

if errors.Is(err, chunk.ErrStageConcurrency) {
	// expected backpressure: upload directly, do not count as failure
	return uploadDirect(key, data)
}

Prevention

Tune --max-staging-write-hours to expected write concurrency
Treat this error as soft backpressure, not failure
Spread heavy writers across clients

When it happens

Trigger: Writing a block to the staging directory when stagingBlocks.Load() already exceeds cache.maxStageWrite (only when maxStageWrite is non-zero), i.e. under very high concurrent write throughput.

Common situations: High-concurrency big-file writes in writeback mode with a low --max-staging-write-hours value; many FUSE clients sharing a small staging concurrency budget.

Related errors

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