What causes "unrecognized hash function: %q" in ipfs/kubo?

Use an exact multihash name, e.g. --hash=sha2-256

unrecognized hash function: %q

Error message

unrecognized hash function: %q

What it means

The `--hash` option must name a multihash function known to go-multihash (e.g. sha2-256, blake2b-256, sha3-512). The lowercased value is looked up in mh.Names; if absent, kubo rejects the add before any data is read.

Source

Thrown at core/commands/add.go:453

			}
			// No explicit preference from user, disable raw-leaves and continue
			rbset = true
			rawblks = false
		}

		if onlyHash && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", onlyHashOptionName, toFilesOptionName)
		}
		if !dopin && pinNameSet {
			return fmt.Errorf("%s option requires %s to be set", pinNameOptionName, pinOptionName)
		}
		if wrap && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", wrapOptionName, toFilesOptionName)
		}

		hashFunCode, ok := mh.Names[strings.ToLower(hashFunStr)]
		if !ok {
			return fmt.Errorf("unrecognized hash function: %q", strings.ToLower(hashFunStr))
		}

		enc, err := cmdenv.GetCidEncoder(req)
		if err != nil {
			return err
		}

		toadd := req.Files
		if wrap {
			toadd = files.NewSliceDirectory([]files.DirEntry{
				files.FileEntry("", req.Files),
			})
		}

		opts := []options.UnixfsAddOption{
			options.Unixfs.Hash(hashFunCode),

			options.Unixfs.Inline(inline),

View on GitHub (pinned to 329838acdf)

Solutions

Use an exact multihash name, e.g. --hash=sha2-256
Verify against known names: sha2-256, sha2-512, sha3-256, sha3-512, blake2b-256, blake2s-256, identity
Fix cfg Import.HashFunction in the config if the resolved default itself is invalid

Example fix

// before
ipfs add --hash=sha256 file.txt
// after
ipfs add --hash=sha2-256 file.txt

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/multiformats/go-multihash"
if _, ok := multihash.Names[strings.ToLower(hashFun)]; !ok {
  return fmt.Errorf("unsupported hash function %q", hashFun)
}

Prevention

Use canonical multihash names (sha2-256, sha3-512, blake2b-256)
Lowercase and validate the --hash value before passing it
Keep Import.HashFunction in config limited to known-good values

When it happens

Trigger: `ipfs add --hash=sha256 file` (wrong alias; correct is sha2-256); `--hash=SHA-256` style variants; config Import.HashFunction containing a misspelled or unsupported name; multihash names unknown to the linked go-multihash table.

Common situations: Typos or wrong aliases (sha256 vs sha2-256, blake2b without a size suffix); copying hash names from other tools; configs migrated from implementations with different naming.

Related errors

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