ipfs/kubo · error

ErrMaxStorageExceeded

ErrMaxStorageExceeded

Error message

maximum storage limit exceeded. Try to unpin some files

What it means

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.

Source

Thrown at core/corerepo/gc.go:20

import (
	"bytes"
	"context"
	"errors"
	"time"

	"github.com/ipfs/kubo/core"
	"github.com/ipfs/kubo/gc"
	"github.com/ipfs/kubo/repo"

	"github.com/dustin/go-humanize"
	"github.com/ipfs/go-cid"
	logging "github.com/ipfs/go-log/v2"
)

var log = logging.Logger("corerepo")

var ErrMaxStorageExceeded = errors.New("maximum storage limit exceeded. Try to unpin some files")

type GC struct {
	Node       *core.IpfsNode
	Repo       repo.Repo
	StorageMax uint64
	StorageGC  uint64
	SlackGB    uint64
	Storage    uint64
}

func NewGC(n *core.IpfsNode) (*GC, error) {
	r := n.Repo
	cfg, err := r.Config()
	if err != nil {
		return nil, err
	}

	// check if cfg has these fields initialized

View on GitHub (pinned to 329838acdf)

Solutions

1. Unpin unneeded data: ipfs pin rm <cid>, then run ipfs repo gc
2. Run ipfs repo gc first to reclaim unpinned space
3. Raise Datastore.StorageMax in the repo config (ipfs config Datastore.StorageMax <size>) and restart the daemon
4. Reduce StorageGC threshold gap so GC triggers earlier (Datastore.StorageGCWatermark / StorageGC), preventing pre-GC warnings from escalating to hard failure

Example fix

// before: failure because everything is pinned
ipfs add bigfile.tar   // ErrMaxStorageExceeded
// after
ipfs pin rm <old-cid>
ipfs repo gc
ipfs config Datastore.StorageMax 100GB
ipfs add bigfile.tar

stat, err := node.Repo.Stat(ctx, true)
if err != nil { return err }
if stat.StorageMax > 0 && stat.StorageStat+incomingBytes > stat.StorageMax {
	return fmt.Errorf("would exceed StorageMax: %d + %d > %d", stat.StorageStat, incomingBytes, stat.StorageMax)
}

if errors.Is(err, corerepo.ErrMaxStorageExceeded) {
	// unpin + gc or raise Datastore.StorageMax before retrying
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• pin check failed: %w
• serveHTTPApi: ConstructNode() failed: %s
• serveHTTPApi: SetAPIAddr() failed: %w
• serveHTTPGateway: SetGatewayAddr() failed: %w
• could not read config: %w

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/46a5babcf7ddeabc. Report an issue: GitHub.