What causes "Import.BatchMaxNodes must be positive, got %d" in ipfs/kubo?

Set Import.BatchMaxNodes to a positive integer (e.g. 128) or remove it for the default

Import.BatchMaxNodes must be positive, got %d

Error message

Import.BatchMaxNodes must be positive, got %d

What it means

ValidateImportConfig requires Import.BatchMaxNodes, the maximum number of nodes buffered in an add batch before flush, to be strictly positive after defaults. A zero or negative batch capacity would prevent the importer from accumulating any nodes.

Source

Thrown at config/import.go:120

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

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

	// Validate UnixFSChunker format
	if !cfg.UnixFSChunker.IsDefault() {
		chunker := cfg.UnixFSChunker.WithDefault(DefaultUnixFSChunker)
		if !isValidChunker(chunker) {
			return fmt.Errorf("Import.UnixFSChunker invalid format: %q (expected \"size-<bytes>\", \"rabin-<min>-<avg>-<max>\", or \"buzhash\")", chunker)
		}
	}

View on GitHub (pinned to 329838acdf)

Solutions

Set Import.BatchMaxNodes to a positive integer (e.g. 128) or remove it for the default
Fix any script computing the value so it clamps to >= 1
Cross-check related Import.BatchMaxSize to keep the batch parameters consistent

Example fix

// before
{"Import": {"BatchMaxNodes": 0}}
// after
{"Import": {"BatchMaxNodes": 128}}

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

if err := config.ValidateImportConfig(&importCfg); err != nil {
	if strings.Contains(err.Error(), "BatchMaxNodes must be positive") {
		importCfg.BatchMaxNodes = config.DefaultBatchMaxNodes
		err = config.ValidateImportConfig(&importCfg)
	}
	return err
}

Prevention

Omit the key for defaults instead of writing 0
Clamp generated values to >= 1
Tune BatchMaxNodes and BatchMaxSize together and re-run validation after changes

When it happens

Trigger: Setting Import.BatchMaxNodes to 0 or a negative value in the config and starting the daemon or running `ipfs add`.

Common situations: Hand-edited configs where 0 was assumed to mean 'unbounded'; scripted config generation with failed arithmetic; tuning add performance with invalid values.

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

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