{"record":{"id":"46a5babcf7ddeabc","repo":"ipfs/kubo","slug":"errmaxstorageexceeded","errorCode":"ErrMaxStorageExceeded","errorMessage":"maximum storage limit exceeded. Try to unpin some files","messagePattern":"maximum storage limit exceeded\\. Try to unpin some files","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/corerepo/gc.go","lineNumber":20,"sourceCode":"\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"errors\"\n\t\"time\"\n\n\t\"github.com/ipfs/kubo/core\"\n\t\"github.com/ipfs/kubo/gc\"\n\t\"github.com/ipfs/kubo/repo\"\n\n\t\"github.com/dustin/go-humanize\"\n\t\"github.com/ipfs/go-cid\"\n\tlogging \"github.com/ipfs/go-log/v2\"\n)\n\nvar log = logging.Logger(\"corerepo\")\n\nvar ErrMaxStorageExceeded = errors.New(\"maximum storage limit exceeded. Try to unpin some files\")\n\ntype GC struct {\n\tNode       *core.IpfsNode\n\tRepo       repo.Repo\n\tStorageMax uint64\n\tStorageGC  uint64\n\tSlackGB    uint64\n\tStorage    uint64\n}\n\nfunc NewGC(n *core.IpfsNode) (*GC, error) {\n\tr := n.Repo\n\tcfg, err := r.Config()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// check if cfg has these fields initialized","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/corerepo/gc.go#L2-L38","documentation":"ErrMaxStorageExceeded is a sentinel error (errors.New, comparable with errors.Is) declared in corerepo. maybeGC returns it when the repo's projected storage (current usage plus the incoming write offset) exceeds StorageGC, and it cannot be resolved by garbage collection because it also exceeds StorageMax. The message tells the user that no amount of GC can free enough space and pins must be removed.","triggerScenarios":"Writing data (e.g. ipfs add, files write, import) when storage+offset already exceeds both gc.StorageGC and gc.StorageMax, so even a full garbage collection would not bring usage under the configured cap. Configured via Datastore.StorageMax in the repo config.","commonSituations":"Node configured with a small Datastore.StorageMax while accumulating many pinned files or MFS content; forgot that pinned data is never GC'd; StorageGC set too close to StorageMax so GC window is too small; disk quota hit during bulk imports.","solutions":["Unpin unneeded data: ipfs pin rm <cid>, then run ipfs repo gc","Run ipfs repo gc first to reclaim unpinned space","Raise Datastore.StorageMax in the repo config (ipfs config Datastore.StorageMax <size>) and restart the daemon","Reduce StorageGC threshold gap so GC triggers earlier (Datastore.StorageGCWatermark / StorageGC), preventing pre-GC warnings from escalating to hard failure"],"exampleFix":"// before: failure because everything is pinned\nipfs add bigfile.tar   // ErrMaxStorageExceeded\n// after\nipfs pin rm <old-cid>\nipfs repo gc\nipfs config Datastore.StorageMax 100GB\nipfs add bigfile.tar","handlingStrategy":"validation","validationCode":"stat, err := node.Repo.Stat(ctx, true)\nif err != nil { return err }\nif stat.StorageMax > 0 && stat.StorageStat+incomingBytes > stat.StorageMax {\n\treturn fmt.Errorf(\"would exceed StorageMax: %d + %d > %d\", stat.StorageStat, incomingBytes, stat.StorageMax)\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, corerepo.ErrMaxStorageExceeded) {\n\t// unpin + gc or raise Datastore.StorageMax before retrying\n}","preventionTips":["Set Datastore.StorageMax comfortably above steady-state usage","Monitor ipfs repo stat in automation before bulk adds","Keep StorageGC well below StorageMax so GC reclaims space before the hard limit","Audit pinset regularly; pinned data is exempt from GC"],"tags":["repo","gc","storage-limit","pinning"],"backgroundTag":"storage-quota-exceeded","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}