ipfs/kubo · error

Import.UnixFSChunker invalid format: %q (expected "size-<byt

Error message

Import.UnixFSChunker invalid format: %q (expected "size-<bytes>", "rabin-<min>-<avg>-<max>", or "buzhash")

What it means

ValidateImportConfig checks Import.UnixFSChunker against the supported chunker syntax: "size-<bytes>", "rabin-<min>-<avg>-<max>", or "buzhash". If the configured string does not match any accepted format (isValidChunker fails), import is rejected with this error naming the offending value.

Source

Thrown at config/import.go:136

		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)
		}
		// Check if the hash is allowed by verifcid
		if !verifcid.DefaultAllowlist.IsAllowed(hashCode) {
			return fmt.Errorf("Import.HashFunction %q is not allowed for use in IPFS", hashFunc)
		}
	}

	// Validate UnixFSHAMTDirectorySizeEstimation
	if !cfg.UnixFSHAMTDirectorySizeEstimation.IsDefault() {

View on GitHub (pinned to 329838acdf)

Solutions

1. Rewrite the chunker in a valid format: "size-262144", "rabin-262144-524288-1048576", or "buzhash"
2. Remove Import.UnixFSChunker to use DefaultUnixFSChunker
3. Test the format with `ipfs add --chunker <value>` before writing it into the config

Example fix

// before
{"Import": {"UnixFSChunker": "size"}}
// after
{"Import": {"UnixFSChunker": "size-262144"}}

var chunkerRe = regexp.MustCompile(`^(size-\d+|rabin-\d+-\d+-\d+|buzhash)$`)
func validChunker(s string) bool { return chunkerRe.MatchString(s) }

if err := config.ValidateImportConfig(&importCfg); err != nil {
	if strings.Contains(err.Error(), "UnixFSChunker invalid format") {
		importCfg.UnixFSChunker = config.DefaultUnixFSChunker
		err = config.ValidateImportConfig(&importCfg)
	}
	return err
}

When it happens

Trigger: Setting Import.UnixFSChunker to a malformed string, e.g. "size" (missing -<bytes>), "rabin-1024" (missing min/avg/max), "fixed-262144", or an empty/unknown format, then starting the daemon or adding files.

Common situations: Porting `ipfs add --chunker` values into config with syntax mistakes; forgetting the rabin three-number format; whitespace or case typos in the chunker string.

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.CidVersion must be 0 or 1, got %d
• 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

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