ipfs/kubo · error

Import.UnixFSDirectoryMaxLinks must be non-negative, got %d

Error message

Import.UnixFSDirectoryMaxLinks must be non-negative, got %d

What it means

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.

Source

Thrown at config/import.go:102

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

	// Validate BatchMaxNodes
	if !cfg.BatchMaxNodes.IsDefault() {
		maxNodes := cfg.BatchMaxNodes.WithDefault(DefaultBatchMaxNodes)
		if maxNodes <= 0 {
			return fmt.Errorf("Import.BatchMaxNodes must be positive, got %d", maxNodes)

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Import.UnixFSDirectoryMaxLinks to a non-negative integer (0 typically means 'use default/unlimited')
2. Remove the key to fall back to DefaultUnixFSDirectoryMaxLinks
3. Fix the generating script so the computed value cannot go negative

Example fix

// before
{"Import": {"UnixFSDirectoryMaxLinks": -5}}
// after
{"Import": {"UnixFSDirectoryMaxLinks": 0}}

v := importCfg.UnixFSDirectoryMaxLinks.WithDefault(config.DefaultUnixFSDirectoryMaxLinks)
if v < 0 {
	return fmt.Errorf("Import.UnixFSDirectoryMaxLinks must be non-negative, got %d", v)
}

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

When it happens

Trigger: Setting Import.UnixFSDirectoryMaxLinks to a negative integer in the config and running import validation (daemon start, `ipfs add`).

Common situations: Negative values from subtraction in generated config scripts; hand-edited configs with sign typos; copied templates with placeholder values like -1.

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.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/de66046d39bc2539. Report an issue: GitHub.