produced block is over 2MiB: big blocks can't be exchanged w

Error message

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

What it means

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.

Source

Thrown at core/commands/cmdutils/utils.go:52

	nodeSize, err := n.Size()
	if err != nil {
		return fmt.Errorf("CheckCIDSize: getting node size: %w", err)
	}

	return CheckBlockSize(req, nodeSize)
}

func CheckBlockSize(req *cmds.Request, size uint64) error {
	allowAnyBlockSize, _ := req.Options[AllowBigBlockOptionName].(bool)
	if allowAnyBlockSize {
		return nil
	}

	// Block size is limited to SoftBlockLimit (2MiB) as defined in the bitswap spec.
	// https://specs.ipfs.tech/bitswap-protocol/#block-sizes
	if size > SoftBlockLimit {
		return 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")
	}
	return nil
}

// ValidatePinName validates that a pin name does not exceed the maximum allowed byte length.
// Returns an error if the name exceeds MaxPinNameBytes (255 bytes).
func ValidatePinName(name string) error {
	if name == "" {
		// Empty names are allowed
		return nil
	}

	nameBytes := len([]byte(name))
	if nameBytes > MaxPinNameBytes {
		return fmt.Errorf("pin name is %d bytes (max %d bytes)", nameBytes, MaxPinNameBytes)
	}
	return nil
}

View on GitHub (pinned to 329838acdf)

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

Example fix

// before
ipfs dag put bigfile.json
// after
ipfs add bigfile.json   # UnixFS chunking keeps blocks under 2MiB

Defensive patterns

Strategy: validation

Validate before calling

if len(data) > 2*1024*1024 {
    return errors.New("payload exceeds 2MiB; use UnixFS chunking or --allow-big-block")
}

Try / catch

err := cmdutils.CheckBlockSize(req, size)
if err != nil {
    if strings.Contains(err.Error(), "over 2MiB") {
        return fmt.Errorf("%w; re-run with --allow-big-block if you accept non-transferable blocks", err)
    }
    return err
}

Prevention

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

When it happens

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

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

Related errors

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