{"record":{"id":"ec63b1413c0a9280","repo":"ipfs/kubo","slug":"unknown-layout-d","errorCode":null,"errorMessage":"unknown layout: %d","messagePattern":"unknown layout: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreapi/unixfs.go","lineNumber":198,"sourceCode":"\t\tfileAdder.SizeEstimationMode = settings.SizeEstimationMode\n\t}\n\tfileAdder.NoCopy = settings.NoCopy\n\tfileAdder.CidBuilder = prefix\n\tfileAdder.PreserveMode = settings.PreserveMode\n\tfileAdder.PreserveMtime = settings.PreserveMtime\n\tfileAdder.FileMode = settings.Mode\n\tfileAdder.FileMtime = settings.Mtime\n\tif settings.IncludeEmptyDirsSet {\n\t\tfileAdder.IncludeEmptyDirs = settings.IncludeEmptyDirs\n\t}\n\n\tswitch settings.Layout {\n\tcase options.BalancedLayout:\n\t\t// Default\n\tcase options.TrickleLayout:\n\t\tfileAdder.Trickle = true\n\tdefault:\n\t\treturn path.ImmutablePath{}, fmt.Errorf(\"unknown layout: %d\", settings.Layout)\n\t}\n\n\tif settings.Inline {\n\t\tfileAdder.CidBuilder = cidutil.InlineBuilder{\n\t\t\tBuilder: fileAdder.CidBuilder,\n\t\t\tLimit:   settings.InlineLimit,\n\t\t}\n\t}\n\n\tif settings.OnlyHash {\n\t\tmd := dagtest.Mock()\n\t\temptyDirNode := ft.EmptyDirNode()\n\t\t// Use the same prefix for the \"empty\" MFS root as for the file adder.\n\t\terr := emptyDirNode.SetCidBuilder(fileAdder.CidBuilder)\n\t\tif err != nil {\n\t\t\treturn path.ImmutablePath{}, err\n\t\t}\n\t\t// MFS root for OnlyHash mode: provider is nil since we're not storing/providing anything","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreapi/unixfs.go#L180-L216","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set Layout to options.BalancedLayout or options.TrickleLayout only.","Leave Layout unset and use the options package constructors so defaults are populated correctly.","Re-check any string-to-layout mapping code and validate against the known set before calling Add.","Sync your options package version with the kubo version you run against."],"exampleFix":"// before\nsettings.Layout = 7 // arbitrary\n// after\nsettings.Layout = options.TrickleLayout // or options.BalancedLayout","handlingStrategy":"validation","validationCode":"switch layout {\ncase options.BalancedLayout, options.TrickleLayout:\n\t// ok\ndefault:\n\tlayout = options.BalancedLayout\n}\nopts := []options.UnixfsAddOption{options.Unixfs.Layout(layout)}","typeGuard":"func knownLayout(l int) bool {\n\treturn l == options.BalancedLayout || l == options.TrickleLayout\n}","tryCatchPattern":"p, err := api.Unixfs().Add(ctx, f, opts...)\nif err != nil && strings.Contains(err.Error(), \"unknown layout\") {\n\topts = []options.UnixfsAddOption{} // revert to defaults\n\tp, err = api.Unixfs().Add(ctx, f, opts...)\n}","preventionTips":["Always assign Layout from the options package constants, never raw ints","Reject out-of-range layout values at your app's input boundary","Keep the client options package version in sync with the kubo version"],"tags":["ipfs","add","unixfs","input-validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}