Import.HashFunction %q is not allowed for use in IPFS

Error message

Import.HashFunction %q is not allowed for use in IPFS

What it means

After resolving Import.HashFunction to a multihash code, ValidateImportConfig checks it against verifcid.DefaultAllowlist, the set of hashes kubo allows for CID verification. A syntactically valid multihash that the allowlist rejects (e.g. md5, sha1, or non-standard hashes) is refused with this error, because blocks/CIDs produced with it would not be verifiable on the network.

Source

Thrown at config/import.go:149

	// 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)
		}
	}

	// Validate UnixFSDAGLayout
	if !cfg.UnixFSDAGLayout.IsDefault() {
		layout := cfg.UnixFSDAGLayout.WithDefault(DefaultUnixFSDAGLayout)

View on GitHub (pinned to 329838acdf)

Solutions

Switch Import.HashFunction to an allowed hash such as 'sha2-256' (default), 'sha2-512', or 'blake2b-256': ipfs config Import.HashFunction sha2-256
Reset to default: ipfs config --json Import.HashFunction null
Check whether the hash is permitted via verifcid.DefaultAllowlist in github.com/ipfs/boxo/verifcid before configuring it

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

code, ok := mh.Names[strings.ToLower(name)]
if ok && !verifcid.DefaultAllowlist.IsAllowed(code) {
	return fmt.Errorf("hash %q not allowed by verifcid", name)
}

Type guard

func isAllowlistedHash(name string) bool {
	code, ok := mh.Names[strings.ToLower(name)]
	return ok && verifcid.DefaultAllowlist.IsAllowed(code)
}

Prevention

Stick to sha2-256 (default), sha2-512, or blake2b-256 for imports
Consult verifcid.DefaultAllowlist in boxo before choosing an exotic hash
Remember the constraint is policy (network verifiability), not just syntax

When it happens

Trigger: Setting Import.HashFunction to a real multihash name that verifcid.DefaultAllowlist.IsAllowed() rejects (e.g. 'sha1', 'md5', 'dbl-sha2-256', or uncommon hashes like 'sha3-512' depending on allowlist) and starting the daemon or adding data.

Common situations: Deliberately choosing a 'stronger' or alternative hash for imports without realizing kubo's verifcid policy forbids it; migrating configs between tools where the other tool allows the hash; upgrading kubo where the allowlist is the enforcement point.

Related errors

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