{"record":{"id":"e715944482aa88aa","repo":"ipfs/kubo","slug":"import-unixfshamtdirectorymaxfanout-must-be-a-powe","errorCode":null,"errorMessage":"Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, between 8 and 1024 (got %d)","messagePattern":"Import\\.UnixFSHAMTDirectoryMaxFanout must be a power of 2, between 8 and 1024 \\(got (.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/import.go","lineNumber":112,"sourceCode":"\t\t\treturn fmt.Errorf(\"Import.UnixFSFileMaxLinks must be positive, got %d\", maxLinks)\n\t\t}\n\t}\n\n\t// Validate UnixFSDirectoryMaxLinks\n\tif !cfg.UnixFSDirectoryMaxLinks.IsDefault() {\n\t\tmaxLinks := cfg.UnixFSDirectoryMaxLinks.WithDefault(DefaultUnixFSDirectoryMaxLinks)\n\t\tif maxLinks < 0 {\n\t\t\treturn fmt.Errorf(\"Import.UnixFSDirectoryMaxLinks must be non-negative, got %d\", maxLinks)\n\t\t}\n\t}\n\n\t// Validate UnixFSHAMTDirectoryMaxFanout if set\n\tif !cfg.UnixFSHAMTDirectoryMaxFanout.IsDefault() {\n\t\tfanout := cfg.UnixFSHAMTDirectoryMaxFanout.WithDefault(DefaultUnixFSHAMTDirectoryMaxFanout)\n\n\t\t// Valid values are powers of 2 between 8 and 1024: 8, 16, 32, 64, 128, 256, 512, 1024\n\t\tif fanout < 8 || !isPowerOfTwo(fanout) || fanout > 1024 {\n\t\t\treturn fmt.Errorf(\"Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, between 8 and 1024 (got %d)\", fanout)\n\t\t}\n\t}\n\n\t// Validate BatchMaxNodes\n\tif !cfg.BatchMaxNodes.IsDefault() {\n\t\tmaxNodes := cfg.BatchMaxNodes.WithDefault(DefaultBatchMaxNodes)\n\t\tif maxNodes <= 0 {\n\t\t\treturn fmt.Errorf(\"Import.BatchMaxNodes must be positive, got %d\", maxNodes)\n\t\t}\n\t}\n\n\t// Validate BatchMaxSize\n\tif !cfg.BatchMaxSize.IsDefault() {\n\t\tmaxSize := cfg.BatchMaxSize.WithDefault(DefaultBatchMaxSize)\n\t\tif maxSize <= 0 {\n\t\t\treturn fmt.Errorf(\"Import.BatchMaxSize must be positive, got %d\", maxSize)\n\t\t}\n\t}","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/config/import.go#L94-L130","documentation":"ValidateImportConfig enforces the HAMT directory parameter constraints from the UnixFS spec: UnixFSHAMTDirectoryMaxFanout must be a power of 2 between 8 and 1024 (8, 16, 32, 64, 128, 256, 512, 1024). HAMT bit width is derived from fanout, so any other value produces an out-of-spec DAG.","triggerScenarios":"Setting Import.UnixFSHAMTDirectoryMaxFanout to a value that is not a power of two, or below 8, or above 1024 (e.g. 100, 4, or 2048) and triggering import validation.","commonSituations":"Tuning HAMT fanout for large directories with an arbitrary number like 100; misreading docs and picking a non-power-of-2; porting settings from another implementation with different bounds.","solutions":["Set the fanout to one of the allowed powers of 2: 8, 16, 32, 64, 128, 256, 512, 1024","Remove the key to use DefaultUnixFSHAMTDirectoryMaxFanout (256)","Verify the value with a quick check: n>0 && (n&(n-1))==0, 8<=n<=1024"],"exampleFix":"// before\n{\"Import\": {\"UnixFSHAMTDirectoryMaxFanout\": 100}}\n// after\n{\"Import\": {\"UnixFSHAMTDirectoryMaxFanout\": 128}}","handlingStrategy":"validation","validationCode":"func validFanout(n uint32) bool {\n\treturn n >= 8 && n <= 1024 && n&(n-1) == 0\n}\n// allowed: 8, 16, 32, 64, 128, 256, 512, 1024","typeGuard":null,"tryCatchPattern":"if err := config.ValidateImportConfig(&importCfg); err != nil {\n\tif strings.Contains(err.Error(), \"HAMTDirectoryMaxFanout\") {\n\t\timportCfg.UnixFSHAMTDirectoryMaxFanout = config.DefaultUnixFSHAMTDirectoryMaxFanout\n\t\terr = config.ValidateImportConfig(&importCfg)\n\t}\n\treturn err\n}","preventionTips":["Pick fanout only from 8, 16, 32, 64, 128, 256, 512, 1024 (UnixFS spec)","Verify power-of-2 with n&(n-1)==0 in any tuning script","Omit the key to use the default fanout of 256"],"tags":["config","hamt","unixfs","validation"],"backgroundTag":"invalid-config-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"}