Version.SwarmCheckPercentThreshold must be between 1 and 100

Error message

Version.SwarmCheckPercentThreshold must be between 1 and 100

What it means

DetectNewKuboVersion takes minPercent, the configured Version.SwarmCheckPercentThreshold, and requires it to be between 1 and 100. Zero falls back to the built-in default, but any other out-of-range value is rejected with this error. It is a configuration validation error, not a runtime failure.

Source

Thrown at core/commands/version.go:282

			processPeerstoreEntry(p)
		}
	} else if nd.DHT != nil && nd.DHT.WAN != nil {
		for _, pi := range nd.DHT.WAN.RoutingTable().GetPeerInfos() {
			processPeerstoreEntry(pi.Id)
		}
	} else if nd.DHT != nil && nd.DHT.LAN != nil {
		for _, pi := range nd.DHT.LAN.RoutingTable().GetPeerInfos() {
			processPeerstoreEntry(pi.Id)
		}
	} else {
		return VersionCheckOutput{}, errors.New("could not perform version check due to missing or incompatible DHT configuration")
	}

	if minPercent < 1 || minPercent > 100 {
		if minPercent == 0 {
			minPercent = config.DefaultSwarmCheckPercentThreshold
		} else {
			return VersionCheckOutput{}, errors.New("Version.SwarmCheckPercentThreshold must be between 1 and 100")
		}
	}

	minFraction := float64(minPercent) / 100.0

	// UpdateAvailable flag is set only if minFraction was reached
	greaterFraction := float64(withGreaterVersion) / float64(totalPeersSampled)

	// Gathered metric are returned every time
	return VersionCheckOutput{
		UpdateAvailable:    (greaterFraction >= minFraction),
		RunningVersion:     ourVersion.String(),
		GreatestVersion:    greatestVersionSeen.String(),
		PeersSampled:       totalPeersSampled,
		WithGreaterVersion: withGreaterVersion,
	}, nil
}

View on GitHub (pinned to 329838acdf)

Solutions

Set Version.SwarmCheckPercentThreshold to an integer between 1 and 100 (e.g. 10 for 10%)
If you want the default, remove the key or set it to 0 explicitly
Convert fractional intentions: 0.5 -> 50, 0.1 -> 10
Pass --threshold with a valid integer when invoking 'ipfs version check'

Example fix

// before
ipfs config --json Version.SwarmCheckPercentThreshold 0.5
// after
ipfs config --json Version.SwarmCheckPercentThreshold 50

Defensive patterns

Strategy: validation

Validate before calling

cfg, _ := node.Repo.Config()
p := cfg.Version.SwarmCheckPercentThreshold
if p < 0 || p > 100 {
    return fmt.Errorf("SwarmCheckPercentThreshold must be 0-100, got %d", p)
}

Try / catch

out, err := DetectNewKuboVersion(nd, pct)
if err != nil && strings.Contains(err.Error(), "must be between 1 and 100") {
    // retry with default threshold
    return DetectNewKuboVersion(nd, 0)
}
return out, err

Prevention

Treat SwarmCheckPercentThreshold as an integer percent (1-100), never a fraction
Validate config before passing thresholds into commands
Use 0 explicitly when you want the default

When it happens

Trigger: 'ipfs version check --threshold N' with N outside 1-100 (excluding 0), or a config file where Version.SwarmCheckPercentThreshold is negative or greater than 100 (e.g. a fraction like 0.5 written where a percent integer is expected).

Common situations: Users writing 0.1 (meaning 10%) instead of 10; scripting the check with a computed threshold that can go negative; copying a config snippet with a malformed threshold value.

Related errors

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