ipfs/kubo · error

only sha2-255-32 is allowed with CIDv0

Error message

only sha2-255-32 is allowed with CIDv0

What it means

CIDv0 requires the multihash to be sha2-256 with the default 32-byte length. When a block put's CID prefix requests version 0 with any other hash function or a non-default length, this validator in core/coreiface/options/block.go rejects the settings before the block is written. (Note the message's typo 'sha2-255-32' — it means sha2-256 with length 32.)

Source

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

			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. Use CIDv1 with the desired hash: drop `--cid-version 0` or set `--cid-version=1` so `--mhtype=sha3-256` etc. are accepted.
2. Or keep CIDv0 and use the default multihash: remove `--mhtype`/`--mh-length` overrides (sha2-256, length 32).
3. Programmatically, when pref.Version == 0 set pref.MhType = mh.SHA2_256 and pref.MhLength = -1 (or 32), or bump the prefix to version 1.

Example fix

// before (CLI)
ipfs block put --cid-version=0 --mhtype=sha3-256 data.bin
// after
ipfs block put --cid-version=1 --mhtype=sha3-256 data.bin

func mhValidForV0(pref cid.Prefix) error {
    if pref.Version == 0 && (pref.MhType != mh.SHA2_256 || (pref.MhLength != -1 && pref.MhLength != 32)) {
        return errors.New("CIDv0 requires sha2-256 with 32-byte digest; use --cid-version=1")
    }
    return nil
}

err := api.Block().Put(ctx, data, opts...)
if err != nil && strings.Contains(err.Error(), "sha2-255-32 is allowed with CIDv0") {
    // retry with CIDv1 to allow the custom multihash
    opts = append(opts, options.BlockPut.CidVersion(1))
    _, err = api.Block().Put(ctx, data, opts...)
}

When it happens

Trigger: Calling `api.Block().Put` with options that set cid-version=0 together with a different multihash type (e.g. blake2b-256, sha3-256) or a custom mhLength (not -1 and not 32), e.g. `ipfs block put --cid-version=0 --mhtype=sha3-256` or `--mh-length=16`.

Common situations: CLI users combining `--mhtype` with CIDv0 on block put; scripts that hardened hashing (sha3/blake2) but left legacy `--cid-version 0`; library users building options.CidPrefix with Version=0 and non-default MhType/MhLength.

Related errors

• only dag-pb is allowed with CIDv0
• unknowm mhType %d
• unknowm mhType %d
• Import.CidVersion must be 0 or 1, got %d
• Import.HashFunction unrecognized: %q

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