ipfs/kubo · error

Import.CidVersion must be 0 or 1, got %d

Error message

Import.CidVersion must be 0 or 1, got %d

What it means

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.

Source

Thrown at config/import.go:86

	UnixFSHAMTDirectoryMaxFanout      OptionalInteger
	UnixFSHAMTDirectorySizeThreshold  OptionalBytes
	UnixFSHAMTDirectorySizeEstimation OptionalString // "links", "block", or "disabled"
	UnixFSDAGLayout                   OptionalString // "balanced" or "trickle"
	BatchMaxNodes                     OptionalInteger
	BatchMaxSize                      OptionalInteger
	FastProvideRoot                   Flag
	FastProvideDAG                    Flag
	FastProvideWait                   Flag
}

// ValidateImportConfig validates the Import configuration according to UnixFS spec requirements.
// See: https://specs.ipfs.tech/unixfs/#hamt-structure-and-parameters
func ValidateImportConfig(cfg *Import) error {
	// Validate CidVersion
	if !cfg.CidVersion.IsDefault() {
		cidVer := cfg.CidVersion.WithDefault(DefaultCidVersion)
		if cidVer != 0 && cidVer != 1 {
			return fmt.Errorf("Import.CidVersion must be 0 or 1, got %d", cidVer)
		}
	}

	// Validate UnixFSFileMaxLinks
	if !cfg.UnixFSFileMaxLinks.IsDefault() {
		maxLinks := cfg.UnixFSFileMaxLinks.WithDefault(DefaultUnixFSFileMaxLinks)
		if maxLinks <= 0 {
			return fmt.Errorf("Import.UnixFSFileMaxLinks must be positive, got %d", maxLinks)
		}
	}

	// Validate UnixFSDirectoryMaxLinks
	if !cfg.UnixFSDirectoryMaxLinks.IsDefault() {
		maxLinks := cfg.UnixFSDirectoryMaxLinks.WithDefault(DefaultUnixFSDirectoryMaxLinks)
		if maxLinks < 0 {
			return fmt.Errorf("Import.UnixFSDirectoryMaxLinks must be non-negative, got %d", maxLinks)
		}
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Import.CidVersion to 0 or 1 (e.g. `ipfs config --json Import.CidVersion 1`)
2. Remove the key entirely to fall back to the default CID version
3. Check the config file for a stray or out-of-range numeric value

Example fix

// before
{"Import": {"CidVersion": 2}}
// after
{"Import": {"CidVersion": 1}}

v := importCfg.CidVersion.WithDefault(config.DefaultCidVersion)
if v != 0 && v != 1 {
	return fmt.Errorf("Import.CidVersion must be 0 or 1, got %d", v)
}

if err := config.ValidateImportConfig(&importCfg); err != nil {
	if strings.Contains(err.Error(), "CidVersion must be 0 or 1") {
		importCfg.CidVersion = config.DefaultCidVersion // fall back to default
		err = config.ValidateImportConfig(&importCfg)
	}
	return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Import.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.BatchMaxNodes must be positive, got %d
• Import.BatchMaxSize must be positive, got %d
• Import.UnixFSChunker invalid format: %q (expected "size-<byt

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/8e6f92eb1258cb06. Report an issue: GitHub.