ipfs/kubo · error

unknown layout: %d

Error message

unknown layout: %d

What it means

Add maps the settings.Layout enum to a DAG builder mode: balanced (default) or trickle. If Layout holds any other integer, the switch falls to default and Add aborts with "unknown layout". This indicates a corrupted or out-of-range enum value, not a user-facing string problem (strings are parsed upstream).

Source

Thrown at core/coreapi/unixfs.go:198

		fileAdder.SizeEstimationMode = settings.SizeEstimationMode
	}
	fileAdder.NoCopy = settings.NoCopy
	fileAdder.CidBuilder = prefix
	fileAdder.PreserveMode = settings.PreserveMode
	fileAdder.PreserveMtime = settings.PreserveMtime
	fileAdder.FileMode = settings.Mode
	fileAdder.FileMtime = settings.Mtime
	if settings.IncludeEmptyDirsSet {
		fileAdder.IncludeEmptyDirs = settings.IncludeEmptyDirs
	}

	switch settings.Layout {
	case options.BalancedLayout:
		// Default
	case options.TrickleLayout:
		fileAdder.Trickle = true
	default:
		return path.ImmutablePath{}, fmt.Errorf("unknown layout: %d", settings.Layout)
	}

	if settings.Inline {
		fileAdder.CidBuilder = cidutil.InlineBuilder{
			Builder: fileAdder.CidBuilder,
			Limit:   settings.InlineLimit,
		}
	}

	if settings.OnlyHash {
		md := dagtest.Mock()
		emptyDirNode := ft.EmptyDirNode()
		// Use the same prefix for the "empty" MFS root as for the file adder.
		err := emptyDirNode.SetCidBuilder(fileAdder.CidBuilder)
		if err != nil {
			return path.ImmutablePath{}, err
		}
		// MFS root for OnlyHash mode: provider is nil since we're not storing/providing anything

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Layout to options.BalancedLayout or options.TrickleLayout only.
2. Leave Layout unset and use the options package constructors so defaults are populated correctly.
3. Re-check any string-to-layout mapping code and validate against the known set before calling Add.
4. Sync your options package version with the kubo version you run against.

Example fix

// before
settings.Layout = 7 // arbitrary
// after
settings.Layout = options.TrickleLayout // or options.BalancedLayout

switch layout {
case options.BalancedLayout, options.TrickleLayout:
	// ok
default:
	layout = options.BalancedLayout
}
opts := []options.UnixfsAddOption{options.Unixfs.Layout(layout)}

func knownLayout(l int) bool {
	return l == options.BalancedLayout || l == options.TrickleLayout
}

p, err := api.Unixfs().Add(ctx, f, opts...)
if err != nil && strings.Contains(err.Error(), "unknown layout") {
	opts = []options.UnixfsAddOption{} // revert to defaults
	p, err = api.Unixfs().Add(ctx, f, opts...)
}

When it happens

Trigger: Calling Unixfs().Add with a Layout field set to an integer outside {BalancedLayout, TrickleLayout} — e.g. a numeric cast of an invalid string, a mismatched options package version, or a zero-value struct where zero is not a valid layout constant.

Common situations: Hand-rolled option structs where Layout was assigned from unvalidated user input, version skew between the client's options library and kubo's options package adding new layouts, and generated code mapping layout names to ints incorrectly.

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

• unsupported file type '%s'
• file type %d not supported
• invalid key
• number of providers must be greater than 0
• either the filestore or the urlstore must be enabled to use

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