{"record":{"id":"a4469a83c81dc074","repo":"ipfs/kubo","slug":"depth-limit-exceeded","errorCode":null,"errorMessage":"depth limit exceeded","messagePattern":"depth limit exceeded","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/add.go","lineNumber":31,"sourceCode":"\t\"github.com/ipfs/kubo/core/commands/cmdenv\"\n\t\"github.com/ipfs/kubo/core/commands/cmdutils\"\n\n\t\"github.com/cheggaaa/pb/v3\"\n\t\"github.com/ipfs/boxo/files\"\n\tuio \"github.com/ipfs/boxo/ipld/unixfs/io\"\n\tmfs \"github.com/ipfs/boxo/mfs\"\n\t\"github.com/ipfs/boxo/path\"\n\t\"github.com/ipfs/boxo/verifcid\"\n\tcid \"github.com/ipfs/go-cid\"\n\tcmds \"github.com/ipfs/go-ipfs-cmds\"\n\tipld \"github.com/ipfs/go-ipld-format\"\n\tcoreiface \"github.com/ipfs/kubo/core/coreiface\"\n\t\"github.com/ipfs/kubo/core/coreiface/options\"\n\tmh \"github.com/multiformats/go-multihash\"\n)\n\n// ErrDepthLimitExceeded indicates that the max depth has been exceeded.\nvar ErrDepthLimitExceeded = errors.New(\"depth limit exceeded\")\n\ntype AddEvent struct {\n\tName       string\n\tHash       string `json:\",omitempty\"`\n\tBytes      int64  `json:\",omitempty\"`\n\tSize       string `json:\",omitempty\"`\n\tMode       string `json:\",omitempty\"`\n\tMtime      int64  `json:\",omitempty\"`\n\tMtimeNsecs int    `json:\",omitempty\"`\n}\n\nconst (\n\tpinNameOptionName           = \"pin-name\"\n\tquietOptionName             = \"quiet\"\n\tquieterOptionName           = \"quieter\"\n\tsilentOptionName            = \"silent\"\n\tprogressOptionName          = \"progress\"\n\ttrickleOptionName           = \"trickle\"","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/add.go#L13-L49","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Raise --max-depth (or use -1 for unlimited) in the ipfs add invocation.","In library code, either increase options.Unixfs.Depth or handle the sentinel with errors.Is and stop/split the import.","Restructure or flatten the source directory tree if a bounded depth is required."],"exampleFix":"// before\nipfs add -r --max-depth 2 ./deep-tree   // fails: depth limit exceeded\n// after\nipfs add -r --max-depth -1 ./deep-tree\n// library code\nif errors.Is(err, coreiface.ErrDepthLimitExceeded) {\n    // increase Depth or stop the walk\n}","handlingStrategy":"validation","validationCode":"// bound depth before walking, so Adder never errors\ndepth := opts.Unixfs.Depth\nif depth >= 0 && walkDepth(root) > depth {\n    return fmt.Errorf(\"tree deeper than max-depth %d\", depth)\n}","typeGuard":"func isDepthLimit(err error) bool {\n    return errors.Is(err, coreiface.ErrDepthLimitExceeded)\n}","tryCatchPattern":"addErr := adder.AddAll(ctx, node)\nif errors.Is(addErr, coreiface.ErrDepthLimitExceeded) {\n    // retry with larger Depth or stop import cleanly\n    return handleDepthLimit(addErr)\n}","preventionTips":["Measure directory-tree depth before importing and set --max-depth accordingly (use -1 for unlimited)","Use errors.Is against the exported sentinel, never string matching","For huge trees, split imports into shards rather than raising depth limits blindly"],"tags":["unixfs","import","depth-limit"],"backgroundTag":"depth-limit-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"}