ipfs/kubo · error

Import.HashFunction unrecognized: %q

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'.

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)

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 %q is not allowed for use in IPFS
• unrecognized hash function: %q
• unknowm mhType %d
• unknowm mhType %d
• private network does not work with Routing.Type=auto. Update

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