ipfs/kubo · error

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

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.

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)

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.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, be
• Import.UnixFSHAMTDirectorySizeEstimation must be %q, %q, or
• 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/2c472dc512872318. Report an issue: GitHub.