{"record":{"id":"8b12c2c440d8de94","repo":"ipfs/kubo","slug":"import-unixfsfilemaxlinks-must-be-positive-got-d","errorCode":null,"errorMessage":"Import.UnixFSFileMaxLinks must be positive, got %d","messagePattern":"Import\\.UnixFSFileMaxLinks must be positive, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/import.go","lineNumber":94,"sourceCode":"\tFastProvideWait                   Flag\n}\n\n// ValidateImportConfig validates the Import configuration according to UnixFS spec requirements.\n// See: https://specs.ipfs.tech/unixfs/#hamt-structure-and-parameters\nfunc ValidateImportConfig(cfg *Import) error {\n\t// Validate CidVersion\n\tif !cfg.CidVersion.IsDefault() {\n\t\tcidVer := cfg.CidVersion.WithDefault(DefaultCidVersion)\n\t\tif cidVer != 0 && cidVer != 1 {\n\t\t\treturn fmt.Errorf(\"Import.CidVersion must be 0 or 1, got %d\", cidVer)\n\t\t}\n\t}\n\n\t// Validate UnixFSFileMaxLinks\n\tif !cfg.UnixFSFileMaxLinks.IsDefault() {\n\t\tmaxLinks := cfg.UnixFSFileMaxLinks.WithDefault(DefaultUnixFSFileMaxLinks)\n\t\tif maxLinks <= 0 {\n\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)","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/config/import.go#L76-L112","documentation":"ValidateImportConfig enforces that Import.UnixFSFileMaxLinks, the maximum number of child links per UnixFS file node, is greater than zero after defaults are applied. Zero or negative values would produce invalid or unbuildable UnixFS DAGs, so the importer refuses to run.","triggerScenarios":"Setting Import.UnixFSFileMaxLinks to 0 or a negative integer in the config and triggering import validation (daemon start or `ipfs add`).","commonSituations":"Hand-edited config with 0 meaning 'unlimited' (a wrong assumption); scripted config generation computing a non-positive value; template configs copied with placeholders unfilled.","solutions":["Set Import.UnixFSFileMaxLinks to a positive integer (e.g. 174) or remove it to use the default","Fix scripts computing the value to clamp to at least 1","Review docs/config.md for the semantics and sensible bounds of the option"],"exampleFix":"// before\n{\"Import\": {\"UnixFSFileMaxLinks\": 0}}\n// after\n{\"Import\": {\"UnixFSFileMaxLinks\": 174}}","handlingStrategy":"validation","validationCode":"v := importCfg.UnixFSFileMaxLinks.WithDefault(config.DefaultUnixFSFileMaxLinks)\nif v <= 0 {\n\treturn fmt.Errorf(\"Import.UnixFSFileMaxLinks must be positive, got %d\", v)\n}","typeGuard":null,"tryCatchPattern":"if err := config.ValidateImportConfig(&importCfg); err != nil {\n\tif strings.Contains(err.Error(), \"UnixFSFileMaxLinks must be positive\") {\n\t\treturn fmt.Errorf(\"fix Import.UnixFSFileMaxLinks in your config: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Treat 0 as invalid, not 'unlimited'; omit the key for defaults","Clamp computed values to at least 1 in generated configs","Review docs/config.md for the option's documented range before tuning"],"tags":["config","unixfs","validation","import"],"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"}