{"record":{"id":"258776eb045ae8c9","repo":"juicedata/juicefs","slug":"concurrent-staging-limit-reached","errorCode":null,"errorMessage":"concurrent staging limit reached","messagePattern":"concurrent staging limit reached","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"info","filePath":"pkg/chunk/disk_cache.go","lineNumber":48,"sourceCode":"\t\"strings\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/charlievieth/fastwalk\"\n\t\"github.com/dustin/go-humanize\"\n\t\"github.com/google/uuid\"\n\t\"github.com/juicedata/juicefs/pkg/utils\"\n)\n\nvar (\n\tstagingDir          = \"rawstaging\"\n\tcacheDir            = \"raw\"\n\tmaxIODur            = time.Second * 30\n\tstagingBlocks       atomic.Int64\n\terrStageFull        = errors.New(\"space not enough on device\")\n\terrStageConcurrency = errors.New(\"concurrent staging limit reached\")\n)\n\ntype cacheKey struct {\n\tid   uint64\n\tindx uint32\n\tsize uint32\n}\n\nfunc (k cacheKey) String() string { return fmt.Sprintf(\"%d_%d_%d\", k.id, k.indx, k.size) }\n\ntype pendingFile struct {\n\tkey       string\n\tpage      *Page\n\tdropCache bool\n}\n\ntype diskCache struct {\n\tid         string","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/chunk/disk_cache.go#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\njuicefs mount --writeback --max-staging-write-hours 1 ... \n// after\njuicefs mount --writeback --max-staging-write-hours 8 ...","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if errors.Is(err, chunk.ErrStageConcurrency) {\n\t// expected backpressure: upload directly, do not count as failure\n\treturn uploadDirect(key, data)\n}","preventionTips":["Tune --max-staging-write-hours to expected write concurrency","Treat this error as soft backpressure, not failure","Spread heavy writers across clients"],"tags":["cache","concurrency","backpressure"],"backgroundTag":"rate-limit-exceeded","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}