{"record":{"id":"8e6f92eb1258cb06","repo":"ipfs/kubo","slug":"import-cidversion-must-be-0-or-1-got-d","errorCode":null,"errorMessage":"Import.CidVersion must be 0 or 1, got %d","messagePattern":"Import\\.CidVersion must be 0 or 1, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/import.go","lineNumber":86,"sourceCode":"\tUnixFSHAMTDirectoryMaxFanout      OptionalInteger\n\tUnixFSHAMTDirectorySizeThreshold  OptionalBytes\n\tUnixFSHAMTDirectorySizeEstimation OptionalString // \"links\", \"block\", or \"disabled\"\n\tUnixFSDAGLayout                   OptionalString // \"balanced\" or \"trickle\"\n\tBatchMaxNodes                     OptionalInteger\n\tBatchMaxSize                      OptionalInteger\n\tFastProvideRoot                   Flag\n\tFastProvideDAG                    Flag\n\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}","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/config/import.go#L68-L104","documentation":"ValidateImportConfig checks the Import section of the config before the importer runs. CIDv1 is the only non-legacy CID version supported for imports, so after applying defaults, CidVersion must be 0 or 1; anything else (e.g. 2) is rejected with this error.","triggerScenarios":"Setting Import.CidVersion in the config to an integer other than 0 or 1 (e.g. 2) and starting the node or running an import operation that calls ValidateImportConfig.","commonSituations":"Hand-editing the config file with an invalid value; scripts generating config JSON with wrong CID version numbers; misunderstanding that CIDv0/CIDv1 are the only UnixFS import versions.","solutions":["Set Import.CidVersion to 0 or 1 (e.g. `ipfs config --json Import.CidVersion 1`)","Remove the key entirely to fall back to the default CID version","Check the config file for a stray or out-of-range numeric value"],"exampleFix":"// before\n{\"Import\": {\"CidVersion\": 2}}\n// after\n{\"Import\": {\"CidVersion\": 1}}","handlingStrategy":"validation","validationCode":"v := importCfg.CidVersion.WithDefault(config.DefaultCidVersion)\nif v != 0 && v != 1 {\n\treturn fmt.Errorf(\"Import.CidVersion must be 0 or 1, got %d\", v)\n}","typeGuard":null,"tryCatchPattern":"if err := config.ValidateImportConfig(&importCfg); err != nil {\n\tif strings.Contains(err.Error(), \"CidVersion must be 0 or 1\") {\n\t\timportCfg.CidVersion = config.DefaultCidVersion // fall back to default\n\t\terr = config.ValidateImportConfig(&importCfg)\n\t}\n\treturn err\n}","preventionTips":["Only ever write 0 or 1 to Import.CidVersion; CIDv2 does not exist for UnixFS imports","Omit the key entirely to accept the default CID recipe (which must stay stable)","Never change the default add recipe defaults; new recipes are opt-in profiles"],"tags":["config","cid","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"}