ipfs/kubo · error

only dag-pb is allowed with CIDv0

Error message

only dag-pb is allowed with CIDv0

What it means

This validation error comes from block put option processing: CIDv0 is, by definition, always dag-pb with sha2-256, so when a caller supplies a CID prefix pinned to version 0 with a different multicodec, the settings validator rejects it. The library validates this explicitly (rather than relying on go-cid) to give a clearer, more actionable error than an opaque CID-encoding failure.

Source

Thrown at core/coreiface/options/block.go:127

		// Fixup invalid name for dag-cbor (0x71)
		if format == "cbor" {
			format = "dag-cbor"
		}

		// Set code based on name passed as "format"
		code, err := codeFromName(format)
		if err != nil {
			return err
		}
		settings.CidPrefix.Codec = uint64(code)

		// If CIDv0, ensure all parameters are compatible
		// (in theory go-cid would validate this anyway, but we want to provide better errors)
		pref := settings.CidPrefix
		if pref.Version == 0 {
			if pref.Codec != uint64(mc.DagPb) {
				return fmt.Errorf("only dag-pb is allowed with CIDv0")
			}
			if pref.MhType != mh.SHA2_256 || (pref.MhLength != -1 && pref.MhLength != 32) {
				return fmt.Errorf("only sha2-255-32 is allowed with CIDv0")
			}
		}

		return nil
	}
}

// Hash is an option for Block.Put which specifies the multihash settings to use
// when hashing the object. Default is mh.SHA2_256 (0x12).
// If mhLen is set to -1, default length for the hash will be used
func (blockOpts) Hash(mhType uint64, mhLen int) BlockPutOption {
	return func(settings *BlockPutSettings) error {
		settings.CidPrefix.MhType = mhType
		settings.CidPrefix.MhLength = mhLen
		return nil

View on GitHub (pinned to 329838acdf)

Solutions

1. Drop `--cid-version 0` so the node picks CIDv1, which supports arbitrary codecs: `ipfs block put --cid-codec=raw` (defaults to v1).
2. Or keep CIDv0 and remove the codec override so the data is encoded as dag-pb.
3. Programmatically, set settings.CidPrefix.Codec = uint64(mc.DagPb) when Version == 0, or raise the prefix version to 1.

Example fix

// before (CLI)
ipfs block put --cid-codec=raw --cid-version=0 data.bin
// after
ipfs block put --cid-codec=raw --cid-version=1 data.bin

func cidPrefixValidForV0(pref cid.Prefix) error {
    if pref.Version == 0 && pref.Codec != uint64(mc.DagPb) {
        return errors.New("CIDv0 requires dag-pb codec; use --cid-version=1 for other codecs")
    }
    return nil
}

err := api.Block().Put(ctx, data, opts...)
if err != nil && strings.Contains(err.Error(), "only dag-pb is allowed with CIDv0") {
    // rebuild options with CIDv1 or drop the codec override
    opts = []options.BlockPutOption{options.BlockPut.Codec("raw"), options.BlockPut.CidVersion(1)}
    _, err = api.Block().Put(ctx, data, opts...)
}

When it happens

Trigger: Calling `api.Block().Put` (block put) with options that set `cid-version=0` together with a codec other than dag-pb, e.g. `ipfs block put --cid-codec=raw --cid-version=0`, or programmatically building options.CidPrefix with Version=0 and Codec != DagPb.

Common situations: CLI users combining `--cid-codec raw` (or raw-leaves/etc.) with the default/implicit CIDv0; scripts migrated from legacy block puts now passing an explicit codec; library users constructing a cid.Prefix manually with version 0 and a non-dag-pb codec.

Related errors

• only sha2-255-32 is allowed with CIDv0
• unknowm mhType %d
• Import.CidVersion must be 0 or 1, got %d
• inline-limit %d exceeds maximum allowed size of %d bytes
• invalid format string: %q

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