{"record":{"id":"de66046d39bc2539","repo":"ipfs/kubo","slug":"import-unixfsdirectorymaxlinks-must-be-non-negativ","errorCode":null,"errorMessage":"Import.UnixFSDirectoryMaxLinks must be non-negative, got %d","messagePattern":"Import\\.UnixFSDirectoryMaxLinks must be non-negative, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/import.go","lineNumber":102,"sourceCode":"\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)\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)","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/config/import.go#L84-L120","documentation":"ValidateImportConfig enforces that Import.UnixFSDirectoryMaxLinks, the maximum number of entries per basic (non-HAMT) UnixFS directory node, is zero or positive after defaults; a directory with a negative link cap is nonsensical, so validation rejects it.","triggerScenarios":"Setting Import.UnixFSDirectoryMaxLinks to a negative integer in the config and running import validation (daemon start, `ipfs add`).","commonSituations":"Negative values from subtraction in generated config scripts; hand-edited configs with sign typos; copied templates with placeholder values like -1.","solutions":["Set Import.UnixFSDirectoryMaxLinks to a non-negative integer (0 typically means 'use default/unlimited')","Remove the key to fall back to DefaultUnixFSDirectoryMaxLinks","Fix the generating script so the computed value cannot go negative"],"exampleFix":"// before\n{\"Import\": {\"UnixFSDirectoryMaxLinks\": -5}}\n// after\n{\"Import\": {\"UnixFSDirectoryMaxLinks\": 0}}","handlingStrategy":"validation","validationCode":"v := importCfg.UnixFSDirectoryMaxLinks.WithDefault(config.DefaultUnixFSDirectoryMaxLinks)\nif v < 0 {\n\treturn fmt.Errorf(\"Import.UnixFSDirectoryMaxLinks must be non-negative, got %d\", v)\n}","typeGuard":null,"tryCatchPattern":"if err := config.ValidateImportConfig(&importCfg); err != nil {\n\tif strings.Contains(err.Error(), \"UnixFSDirectoryMaxLinks must be non-negative\") {\n\t\treturn fmt.Errorf(\"fix Import.UnixFSDirectoryMaxLinks in your config: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Never write negative values; omit the key for defaults","Guard scripts that compute the value against underflow/subtraction errors","Search copied config templates for placeholder values like -1 before deploying"],"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"}