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

Set Import.BatchMaxSize to a positive byte value (e.g. 1<<27) or remove it for the default

Import.BatchMaxSize must be positive, got %d

Error message

Import.BatchMaxSize must be positive, got %d

What it means

ValidateImportConfig requires Import.BatchMaxSize, the maximum cumulative byte size of an add batch before it is flushed, to be strictly positive after defaults. A non-positive batch size makes the batching logic invalid, so startup or import aborts with this error.

Source

Thrown at config/import.go:128

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

	// Validate HashFunction
	if !cfg.HashFunction.IsDefault() {
		hashFunc := cfg.HashFunction.WithDefault(DefaultHashFunction)
		hashCode, ok := mh.Names[strings.ToLower(hashFunc)]
		if !ok {
			return fmt.Errorf("Import.HashFunction unrecognized: %q", hashFunc)
		}

View on GitHub (pinned to 329838acdf)

Solutions

Set Import.BatchMaxSize to a positive byte value (e.g. 1<<27) or remove it for the default
Verify unit conversions in scripts that compute the size (MiB/GiB)
Keep BatchMaxSize consistent with BatchMaxNodes when tuning

Example fix

// before
{"Import": {"BatchMaxSize": 0}}
// after
{"Import": {"BatchMaxSize": 134217728}}

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Use explicit byte literals (e.g. 1<<27) to avoid unit-conversion mistakes
Omit the key for defaults instead of writing 0
Validate generated configs before deploying them to nodes

When it happens

Trigger: Setting Import.BatchMaxSize to 0 or a negative byte count in the config and running the daemon or an import.

Common situations: Hand-edited configs with 0 assumed to mean 'no limit'; size computations in scripts yielding 0 (e.g. unit conversion mistakes); copied example configs with placeholders.

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