{"record":{"id":"6ef69a4429bc7d9e","repo":"ipfs/kubo","slug":"produced-block-is-over-2mib-big-blocks-can-t-be-e","errorCode":null,"errorMessage":"produced block is over 2MiB: big blocks can't be exchanged with other peers. consider using UnixFS for automatic chunking of bigger files, or pass --allow-big-block to override","messagePattern":"produced block is over 2MiB: big blocks can't be exchanged with other peers\\. consider using UnixFS for automatic chunking of bigger files, or pass --allow-big-block to override","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/cmdutils/utils.go","lineNumber":52,"sourceCode":"\n\tnodeSize, err := n.Size()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"CheckCIDSize: getting node size: %w\", err)\n\t}\n\n\treturn CheckBlockSize(req, nodeSize)\n}\n\nfunc CheckBlockSize(req *cmds.Request, size uint64) error {\n\tallowAnyBlockSize, _ := req.Options[AllowBigBlockOptionName].(bool)\n\tif allowAnyBlockSize {\n\t\treturn nil\n\t}\n\n\t// Block size is limited to SoftBlockLimit (2MiB) as defined in the bitswap spec.\n\t// https://specs.ipfs.tech/bitswap-protocol/#block-sizes\n\tif size > SoftBlockLimit {\n\t\treturn fmt.Errorf(\"produced block is over 2MiB: big blocks can't be exchanged with other peers. consider using UnixFS for automatic chunking of bigger files, or pass --allow-big-block to override\")\n\t}\n\treturn nil\n}\n\n// ValidatePinName validates that a pin name does not exceed the maximum allowed byte length.\n// Returns an error if the name exceeds MaxPinNameBytes (255 bytes).\nfunc ValidatePinName(name string) error {\n\tif name == \"\" {\n\t\t// Empty names are allowed\n\t\treturn nil\n\t}\n\n\tnameBytes := len([]byte(name))\n\tif nameBytes > MaxPinNameBytes {\n\t\treturn fmt.Errorf(\"pin name is %d bytes (max %d bytes)\", nameBytes, MaxPinNameBytes)\n\t}\n\treturn nil\n}","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/cmdutils/utils.go#L34-L70","documentation":"CheckBlockSize enforces the bitswap soft block limit of 2MiB: blocks larger than that cannot be exchanged with other peers over standard bitswap. When a produced block exceeds SoftBlockLimit, this error is returned telling the user to use UnixFS chunking or pass --allow-big-block. It is an intentional safety guard, not a bug.","triggerScenarios":"`ipfs dag put` (or add with --inline/-chunk settings) creating a single block over 2MiB; passing a huge raw payload to dag put without chunking; explicitly enabling --allow-big-block flows that still validate.","commonSituations":"Users putting large JSON/CBOR documents via `ipfs dag put` without splitting; add with `--chunk-size` larger than 2MiB; migrated scripts from nodes with bigger limits.","solutions":["Use UnixFS (`ipfs add`) so large files are automatically chunked into sub-2MiB blocks","Split large documents into multiple DAG nodes instead of one block","Pass --allow-big-block to override, accepting the block will not be transferable over standard bitswap"],"exampleFix":"// before\nipfs dag put bigfile.json\n// after\nipfs add bigfile.json   # UnixFS chunking keeps blocks under 2MiB","handlingStrategy":"validation","validationCode":"if len(data) > 2*1024*1024 {\n    return errors.New(\"payload exceeds 2MiB; use UnixFS chunking or --allow-big-block\")\n}","typeGuard":null,"tryCatchPattern":"err := cmdutils.CheckBlockSize(req, size)\nif err != nil {\n    if strings.Contains(err.Error(), \"over 2MiB\") {\n        return fmt.Errorf(\"%w; re-run with --allow-big-block if you accept non-transferable blocks\", err)\n    }\n    return err\n}","preventionTips":["Use `ipfs add` (UnixFS) for anything larger than 2MiB","Keep --chunk-size below the 2MiB soft limit","Reserve --allow-big-block for deliberate, isolated use cases"],"tags":["blocksize","bitswap","dag","unixfs"],"backgroundTag":"block-too-large","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"}