ipfs/kubo · error

Import.HashFunction unrecognized

Error message

Import.HashFunction unrecognized: %q

What it means

ValidateImportConfig rejects Import.HashFunction values that are not a known multihash name. The config string is lowercased and looked up in mh.Names (go-multihash); if no multihash code matches, startup/config-validation fails with this error. It exists so an invalid hash name is caught at daemon startup instead of at first 'ipfs add'.

Solutions

1. Check the exact multihash name against https://github.com/multiformats/go-multihash/blob/master/multihash.go (e.g. 'sha2-256', 'sha2-512', 'blake2b-256') and set it with: ipfs config Import.HashFunction sha2-256
2. Remove the setting to fall back to the default: ipfs config --json Import.HashFunction null (default is 'sha2-256')
3. Trim whitespace/case issues — the lookup lowercases the value, but embedded spaces or trailing newline (e.g. from shell substitution) will fail; set the value again carefully

Example fix

// before
ipfs config Import.HashFunction sha256
// after
ipfs config Import.HashFunction sha2-256

func validHashFunc(name string) bool {
	_, ok := mh.Names[strings.ToLower(name)]
	return ok
}
if !validHashFunc(cfg.Import.HashFunction.WithDefault("sha2-256")) {
	return fmt.Errorf("bad Import.HashFunction")
}

func isKnownMultihash(name string) bool {
	_, ok := mh.Names[strings.ToLower(strings.TrimSpace(name))]
	return ok
}

When it happens

Trigger: Setting Import.HashFunction in the kubo config (ipfs config Import.HashFunction <value>) to a string not in mh.Names — e.g. a typo ('sha256' without the dash, 'sha3-512x'), a made-up algorithm name, or extra whitespace — then starting the daemon or calling ValidateImportConfig.

Common situations: Typo in the hash name ('sha2-256' written as 'sha-256' or 'sha256'); copying a hash name from another tool with different naming; setting an algorithm that exists as a multihash but is so obscure it is fine here yet fails later at error 111 (this one is strictly 'unknown name').

Related errors

• Import.HashFunction is not allowed for use in IPFS
• unrecognized hash function
• "all" strategy cannot be combined with other strategies in
• cannot specify negative resolve cache size
• cannot specify negative resolve cache size

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

Appendix: source

Thrown at config/import.go:145

		if maxSize <= 0 {
			return fmt.Errorf("Import.BatchMaxSize must be positive, got %d", maxSize)
		}
	}

	// Validate UnixFSChunker format
	if !cfg.UnixFSChunker.IsDefault() {
		chunker := cfg.UnixFSChunker.WithDefault(DefaultUnixFSChunker)
		if !isValidChunker(chunker) {
			return fmt.Errorf("Import.UnixFSChunker invalid format: %q (expected \"size-<bytes>\", \"rabin-<min>-<avg>-<max>\", or \"buzhash\")", chunker)
		}
	}

	// Validate HashFunction
	if !cfg.HashFunction.IsDefault() {
		hashFunc := cfg.HashFunction.WithDefault(DefaultHashFunction)
		hashCode, ok := mh.Names[strings.ToLower(hashFunc)]
		if !ok {
			return fmt.Errorf("Import.HashFunction unrecognized: %q", hashFunc)
		}
		// Check if the hash is allowed by verifcid
		if !verifcid.DefaultAllowlist.IsAllowed(hashCode) {
			return fmt.Errorf("Import.HashFunction %q is not allowed for use in IPFS", hashFunc)
		}
	}

	// Validate UnixFSHAMTDirectorySizeEstimation
	if !cfg.UnixFSHAMTDirectorySizeEstimation.IsDefault() {
		est := cfg.UnixFSHAMTDirectorySizeEstimation.WithDefault(DefaultUnixFSHAMTDirectorySizeEstimation)
		switch est {
		case HAMTSizeEstimationLinks, HAMTSizeEstimationBlock, HAMTSizeEstimationDisabled:
			// valid
		default:
			return fmt.Errorf("Import.UnixFSHAMTDirectorySizeEstimation must be %q, %q, or %q, got %q",
				HAMTSizeEstimationLinks, HAMTSizeEstimationBlock, HAMTSizeEstimationDisabled, est)
		}
	}

View on GitHub (pinned to 329838acdf)