{"record":{"id":"f4b8dde1a0a55552","repo":"ipfs/kubo","slug":"hamt-fanout-must-be-a-power-of-2-between-8-and-10","errorCode":null,"errorMessage":"HAMT fanout must be a power of 2, between 8 and 1024 (got %d)","messagePattern":"HAMT fanout must be a power of 2, between 8 and 1024 \\(got (.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/unixfs.go","lineNumber":241,"sourceCode":"}\n\n// MaxDirectoryLinks specifies the maximum number of children for UnixFS basic\n// directory nodes.\nfunc (unixfsOpts) MaxDirectoryLinks(n int) UnixfsAddOption {\n\treturn func(settings *UnixfsAddSettings) error {\n\t\tsettings.MaxDirectoryLinks = n\n\t\tsettings.MaxDirectoryLinksSet = true\n\t\treturn nil\n\t}\n}\n\n// MaxHAMTFanout specifies the maximum width of the HAMT directory shards.\n// Per the UnixFS spec, the value must be a power of 2, minimum 8\n// (for byte-aligned bitfields), and maximum 1024.\nfunc (unixfsOpts) MaxHAMTFanout(n int) UnixfsAddOption {\n\treturn func(settings *UnixfsAddSettings) error {\n\t\tif n < 8 || n&(n-1) != 0 || n > 1024 {\n\t\t\treturn fmt.Errorf(\"HAMT fanout must be a power of 2, between 8 and 1024 (got %d)\", n)\n\t\t}\n\t\tsettings.MaxHAMTFanout = n\n\t\tsettings.MaxHAMTFanoutSet = true\n\t\treturn nil\n\t}\n}\n\n// SizeEstimationMode specifies how directory size is estimated for HAMT sharding decisions.\nfunc (unixfsOpts) SizeEstimationMode(mode io.SizeEstimationMode) UnixfsAddOption {\n\treturn func(settings *UnixfsAddSettings) error {\n\t\tsettings.SizeEstimationMode = &mode\n\t\tsettings.SizeEstimationModeSet = true\n\t\treturn nil\n\t}\n}\n\n// Inline tells the adder to inline small blocks into CIDs\nfunc (unixfsOpts) Inline(enable bool) UnixfsAddOption {","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/unixfs.go#L223-L259","documentation":"When sharding a directory as a HAMT, the fanout is the width of each shard's bitfield. The UnixFS spec constrains it to a power of 2 between 8 and 1024 so the bitfield stays byte-aligned; MaxHAMTFanout rejects any other value up front.","triggerScenarios":"Calling options.Unixfs.MaxHAMTFanout(n) with n < 8 (e.g. 4), n > 1024 (e.g. 2048), or n not a power of two (e.g. 100, 300), then passing the option to UnixfsAddOptions/Add.","commonSituations":"Reading 'fanout' defaults from other tools (js-ipfs HAMT uses 2048 in some configs, which kubo rejects); computing fanout as bucket count from data size; typos like 1250; users porting configs where a non-power-of-2 was tolerated.","solutions":["Pick the nearest valid power of two within [8,1024]: 8, 16, 32, 64, 128, 256, 512, or 1024","If the desired value exceeds 1024 (e.g. js-ipfs 2048), clamp to 1024 — it is the maximum the UnixFS spec allows","If you did not set fanout intentionally, drop the MaxHAMTFanout option and let the default apply"],"exampleFix":"// before\nopt := options.Unixfs.MaxHAMTFanout(2048) // error: between 8 and 1024\n\n// after\nopt := options.Unixfs.MaxHAMTFanout(1024)","handlingStrategy":"validation","validationCode":"func clampHAMTFanout(n int) int {\n    if n < 8 {\n        return 8\n    }\n    if n > 1024 {\n        return 1024\n    }\n    // snap up to next power of two\n    p := 8\n    for p < n {\n        p *= 2\n    }\n    return p\n}\nn := clampHAMTFanout(desired)\nopt := options.Unixfs.MaxHAMTFanout(n)","typeGuard":"func isPowerOfTwoInRange8to1024(n int) bool {\n    return n >= 8 && n <= 1024 && n&(n-1) == 0\n}","tryCatchPattern":"opts, err := options.Unixfs.Add(options.Unixfs.MaxHAMTFanout(n))\nif err != nil {\n    if strings.Contains(err.Error(), \"HAMT fanout\") {\n        // retry with spec-legal default\n        opts, err = options.Unixfs.Add(options.Unixfs.MaxHAMTFanout(256))\n    }\n    if err != nil {\n        return err\n    }\n}","preventionTips":["Restrict fanout values to {8,16,32,64,128,256,512,1024}","Snap user input to the nearest power of two before calling MaxHAMTFanout","Values above 1024 (e.g. js-ipfs 2048) must be clamped to 1024 per the UnixFS spec","If unsure, skip the option and use the library default fanout"],"tags":["unixfs","hamt","validation","options"],"backgroundTag":"hamt-fanout-out-of-range","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"}