ipfs/kubo · error

Import.UnixFSDAGLayout must be

Error message

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

What it means

Import.UnixFSDAGLayout selects the UnixFS DAG layout used when importing files: 'balanced' (default) or 'trickle'. ValidateImportConfig accepts only these two exact strings and returns this error for any other value, catching bad layouts before any data is imported.

Solutions

1. Set the layout to exactly 'balanced' or 'trickle': ipfs config Import.UnixFSDAGLayout balanced
2. Remove the setting to use the default 'balanced': ipfs config --json Import.UnixFSDAGLayout null
3. Use the CLI flag '--trickle' per-invocation instead of a config value if trickle is only needed for one add

Example fix

// before
ipfs config Import.UnixFSDAGLayout trickle-dag
// after
ipfs config Import.UnixFSDAGLayout trickle

valid := map[string]bool{"balanced": true, "trickle": true}
if v := layout.WithDefault("balanced"); !valid[v] {
	return fmt.Errorf("UnixFSDAGLayout must be balanced|trickle")
}

func isDAGLayout(s string) bool {
	return s == "balanced" || s == "trickle"
}

When it happens

Trigger: Setting Import.UnixFSDAGLayout to a string other than 'balanced' or 'trickle' — e.g. the old CLI flag value 'trickle-dag', 'default', or a capitalized 'Balanced' — then starting the daemon.

Common situations: Copy-pasting the legacy '--trickle' flag name into the config; assuming other layouts (e.g. 'flat') exist; hand-editing config.json with casing mistakes.

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.UnixFSDirectoryMaxLinks must be non-negative, got
• Import.UnixFSFileMaxLinks must be positive, got
• Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2…
• Import.UnixFSHAMTDirectorySizeEstimation must be
• "all" strategy cannot be combined with other strategies in

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

Appendix: source

Thrown at config/import.go:172

	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
}

// isPowerOfTwo checks if a number is a power of 2
func isPowerOfTwo(n int64) bool {
	return n > 0 && (n&(n-1)) == 0
}

// isValidChunker validates chunker format
func isValidChunker(chunker string) bool {
	if chunker == "buzhash" {
		return true
	}

View on GitHub (pinned to 329838acdf)