ipfs/kubo · error

Import.UnixFSHAMTDirectorySizeEstimation must be %q, %q, or

Error message

Import.UnixFSHAMTDirectorySizeEstimation must be %q, %q, or %q, got %q

What it means

Import.UnixFSHAMTDirectorySizeEstimation controls how HAMT directory shard sizes are estimated when importing ('links', 'block', or 'disabled'). ValidateImportConfig uses an exhaustive switch and rejects any other string, so a misspelled or foreign value fails config validation at startup.

Source

Thrown at config/import.go:160

		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)
		switch layout {
		case DAGLayoutBalanced, DAGLayoutTrickle:
			// valid
		default:
			return fmt.Errorf("Import.UnixFSDAGLayout must be %q or %q, got %q",
				DAGLayoutBalanced, DAGLayoutTrickle, layout)
		}
	}

	return nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Set the value to one of exactly 'links', 'block', or 'disabled': ipfs config Import.UnixFSHAMTDirectorySizeEstimation links
2. Remove the setting to use the default 'links': ipfs config --json Import.UnixFSHAMTDirectorySizeEstimation null
3. If the intent was to disable HAMT sharding entirely, use 'disabled' (not 'none' or 'off')

Example fix

// before
ipfs config Import.UnixFSHAMTDirectorySizeEstimation none
// after
ipfs config Import.UnixFSHAMTDirectorySizeEstimation disabled

valid := map[string]bool{"links": true, "block": true, "disabled": true}
if v := est.WithDefault("links"); !valid[v] {
	return fmt.Errorf("UnixFSHAMTDirectorySizeEstimation must be links|block|disabled")
}

func isHAMTSizeEstimation(s string) bool {
	switch s {
	case "links", "block", "disabled":
		return true
	}
	return false
}

When it happens

Trigger: Setting Import.UnixFSHAMTDirectorySizeEstimation to anything other than the exact strings 'links', 'block', or 'disabled' (case-sensitive) — e.g. 'true', 'none', 'Links', 'off' — then starting the daemon or running ValidateImportConfig.

Common situations: Typo or wrong casing when hand-editing the config; guessing value names from documentation of a different option; scripting config writes with unvalidated user input.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, be
• Import.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.UnixFSDAGLayout must be %q or %q, got %q
• HAMT fanout must be a power of 2, between 8 and 1024 (got %d

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