ipfs/kubo · error

depth limit exceeded

Error message

depth limit exceeded

What it means

core/commands/add.go declares ErrDepthLimitExceeded, the sentinel error returned when adding a UnixFS tree whose directory nesting exceeds the configured --max-depth (or the default depth limit). Adders can compare with errors.Is(err, coreiface.ErrDepthLimitExceeded) to detect this case and e.g. shard or stop gracefully.

Source

Thrown at core/commands/add.go:31

	"github.com/ipfs/kubo/core/commands/cmdenv"
	"github.com/ipfs/kubo/core/commands/cmdutils"

	"github.com/cheggaaa/pb/v3"
	"github.com/ipfs/boxo/files"
	uio "github.com/ipfs/boxo/ipld/unixfs/io"
	mfs "github.com/ipfs/boxo/mfs"
	"github.com/ipfs/boxo/path"
	"github.com/ipfs/boxo/verifcid"
	cid "github.com/ipfs/go-cid"
	cmds "github.com/ipfs/go-ipfs-cmds"
	ipld "github.com/ipfs/go-ipld-format"
	coreiface "github.com/ipfs/kubo/core/coreiface"
	"github.com/ipfs/kubo/core/coreiface/options"
	mh "github.com/multiformats/go-multihash"
)

// ErrDepthLimitExceeded indicates that the max depth has been exceeded.
var ErrDepthLimitExceeded = errors.New("depth limit exceeded")

type AddEvent struct {
	Name       string
	Hash       string `json:",omitempty"`
	Bytes      int64  `json:",omitempty"`
	Size       string `json:",omitempty"`
	Mode       string `json:",omitempty"`
	Mtime      int64  `json:",omitempty"`
	MtimeNsecs int    `json:",omitempty"`
}

const (
	pinNameOptionName           = "pin-name"
	quietOptionName             = "quiet"
	quieterOptionName           = "quieter"
	silentOptionName            = "silent"
	progressOptionName          = "progress"
	trickleOptionName           = "trickle"

View on GitHub (pinned to 329838acdf)

Solutions

1. Raise --max-depth (or use -1 for unlimited) in the ipfs add invocation.
2. In library code, either increase options.Unixfs.Depth or handle the sentinel with errors.Is and stop/split the import.
3. Restructure or flatten the source directory tree if a bounded depth is required.

Example fix

// before
ipfs add -r --max-depth 2 ./deep-tree   // fails: depth limit exceeded
// after
ipfs add -r --max-depth -1 ./deep-tree
// library code
if errors.Is(err, coreiface.ErrDepthLimitExceeded) {
    // increase Depth or stop the walk
}

// bound depth before walking, so Adder never errors
depth := opts.Unixfs.Depth
if depth >= 0 && walkDepth(root) > depth {
    return fmt.Errorf("tree deeper than max-depth %d", depth)
}

func isDepthLimit(err error) bool {
    return errors.Is(err, coreiface.ErrDepthLimitExceeded)
}

addErr := adder.AddAll(ctx, node)
if errors.Is(addErr, coreiface.ErrDepthLimitExceeded) {
    // retry with larger Depth or stop import cleanly
    return handleDepthLimit(addErr)
}

When it happens

Trigger: `ipfs add -r --max-depth N` on a directory tree deeper than N; programmatic adds via unixfs Adder with Depth set, walking deeper than the limit.

Common situations: Importing large filesystems with very deep directory hierarchies (node_modules, source trees) with a low --max-depth; archival scripts that set depth limits to bound DAG size.

Related errors

• Import.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• unsupported file type '%s'
• file type %d not supported
• unexpected Objects len

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