ipfs/kubo · error

Import.UnixFSFileMaxLinks must be positive, got %d

Error message

Import.UnixFSFileMaxLinks must be positive, got %d

What it means

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.

Source

Thrown at config/import.go:94

	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)
		}
	}

	// Validate UnixFSHAMTDirectoryMaxFanout if set
	if !cfg.UnixFSHAMTDirectoryMaxFanout.IsDefault() {
		fanout := cfg.UnixFSHAMTDirectoryMaxFanout.WithDefault(DefaultUnixFSHAMTDirectoryMaxFanout)

		// Valid values are powers of 2 between 8 and 1024: 8, 16, 32, 64, 128, 256, 512, 1024
		if fanout < 8 || !isPowerOfTwo(fanout) || fanout > 1024 {
			return fmt.Errorf("Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, between 8 and 1024 (got %d)", fanout)

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Import.UnixFSFileMaxLinks to a positive integer (e.g. 174) or remove it to use the default
2. Fix scripts computing the value to clamp to at least 1
3. Review docs/config.md for the semantics and sensible bounds of the option

Example fix

// before
{"Import": {"UnixFSFileMaxLinks": 0}}
// after
{"Import": {"UnixFSFileMaxLinks": 174}}

v := importCfg.UnixFSFileMaxLinks.WithDefault(config.DefaultUnixFSFileMaxLinks)
if v <= 0 {
	return fmt.Errorf("Import.UnixFSFileMaxLinks must be positive, got %d", v)
}

if err := config.ValidateImportConfig(&importCfg); err != nil {
	if strings.Contains(err.Error(), "UnixFSFileMaxLinks must be positive") {
		return fmt.Errorf("fix Import.UnixFSFileMaxLinks in your config: %w", err)
	}
	return err
}

When it happens

Trigger: Setting Import.UnixFSFileMaxLinks to 0 or a negative integer in the config and triggering import validation (daemon start or `ipfs add`).

Common situations: Hand-edited config with 0 meaning 'unlimited' (a wrong assumption); scripted config generation computing a non-positive value; template configs copied with placeholders unfilled.

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.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.CidVersion must be 0 or 1, got %d
• Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, be
• Import.BatchMaxNodes must be positive, got %d
• Import.BatchMaxSize must be positive, got %d

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