ipfs/kubo · error

unrecognized hash function: %q

Error message

unrecognized hash function: %q

What it means

In getPrefix (used by `ipfs files chcid` and related MFS commands), the --hash option string could not be resolved to a known multihash function name when building the cid.Builder. It is a generic option-parsing guard; the unrecognized hash name is quoted in the message, and the command aborts before any node is modified.

Source

Thrown at core/commands/files.go:1502

// getPrefix builds a cid.Builder from CLI flags, falling back to importCfg
// when provided. Returns (nil, nil) when neither CLI nor config set a value.
func getPrefix(req *cmds.Request, importCfg *config.Import) (cid.Builder, error) {
	cidVer, cidVerSet := req.Options[filesCidVersionOptionName].(int)
	hashFunStr, hashFunSet := req.Options[filesHashOptionName].(string)

	if cidVerSet || hashFunSet {
		// CLI flags take precedence: build prefix from them directly.
		if hashFunSet && cidVer == 0 {
			cidVer = 1
		}
		prefix, err := dag.PrefixForCidVersion(cidVer)
		if err != nil {
			return nil, err
		}
		if hashFunSet {
			hashFunCode, ok := mh.Names[strings.ToLower(hashFunStr)]
			if !ok {
				return nil, fmt.Errorf("unrecognized hash function: %q", hashFunStr)
			}
			prefix.MhType = hashFunCode
			prefix.MhLength = -1
		}
		return &prefix, nil
	}

	// No CLI flags: fall back to Import config.
	if importCfg != nil {
		return importCfg.UnixFSCidBuilder()
	}

	return nil, nil
}

func ensureContainingDirectoryExists(r *mfs.Root, path string, opts ...mfs.Option) error {
	dirtomake := gopath.Dir(path)

View on GitHub (pinned to 329838acdf)

Solutions

1. Use a supported multihash name, e.g. --hash sha2-256 or sha2-512.
2. List valid names via the multihash codec registry and re-run the command with a corrected --hash value.

When it happens

Trigger: Thrown at core/commands/files.go:1502 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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