ipfs/kubo · error

invalid provide strategy: empty token in %q

Error message

invalid provide strategy: empty token in %q

What it means

ParseProvideStrategy parses Provide.Strategy, a '+'-separated token list (e.g. 'pinned+mfs'). An empty string is accepted (maps to 'all'), but an empty token produced by splitting — from a leading, trailing, or doubled '+' such as 'pinned+' or 'pinned++mfs' — is invalid and returns this error.

Source

Thrown at config/provide.go:151

	// When enabled, the provider persists its reprovide cycle state and provide queue to the datastore,
	// and restores them on restart. When disabled, the provider starts fresh on each restart.
	// Default: true
	ResumeEnabled Flag `json:",omitempty"`
}

func ParseProvideStrategy(s string) (ProvideStrategy, error) {
	var strategy ProvideStrategy
	for part := range strings.SplitSeq(s, "+") {
		switch part {
		case "all", "flat":
			strategy |= ProvideStrategyAll
		case "":
			// empty string (default config) maps to "all",
			// but empty tokens from splitting (e.g. "pinned+") are invalid
			if s == "" {
				strategy |= ProvideStrategyAll
			} else {
				return 0, fmt.Errorf("invalid provide strategy: empty token in %q", s)
			}
		case "pinned":
			strategy |= ProvideStrategyPinned
		case "roots":
			strategy |= ProvideStrategyRoots
		case "mfs":
			strategy |= ProvideStrategyMFS
		case "unique":
			strategy |= ProvideStrategyUnique
		case "entities":
			strategy |= ProvideStrategyEntities | ProvideStrategyUnique
		default:
			return 0, fmt.Errorf("unknown provide strategy token: %q in %q", part, s)
		}
	}
	// "all" provides every block and cannot be combined with selective strategies
	if strategy&ProvideStrategyAll != 0 && strategy != ProvideStrategyAll {
		return 0, fmt.Errorf("\"all\" strategy cannot be combined with other strategies in %q", s)

View on GitHub (pinned to 329838acdf)

Solutions

1. Remove stray '+' characters so the strategy contains no empty tokens: ipfs config Provide.Strategy pinned+mfs
2. Reset to default by setting an empty string: ipfs config Provide.Strategy '' (empty means 'all')
3. In code, sanitize before parsing: strings.Trim(s, "+") and collapse '+'-runs, or reject tokens after strings.Split(s, "+") that are empty when s != ""

Example fix

// before
ipfs config Provide.Strategy 'pinned+'
// after
ipfs config Provide.Strategy 'pinned'

if s != "" && (strings.HasPrefix(s, "+") || strings.HasSuffix(s, "+") || strings.Contains(s, "++")) {
	return fmt.Errorf("empty token in strategy %q", s)
}
if _, err := config.ParseProvideStrategy(s); err != nil { return err }

func hasNoEmptyTokens(s string) bool {
	if s == "" { return true }
	for part := range strings.SplitSeq(s, "+") {
		if part == "" { return false }
	}
	return true
}

strategy, err := config.ParseProvideStrategy(s)
if err != nil {
	return fmt.Errorf("Provide.Strategy %q invalid: %w", s, err)
}

When it happens

Trigger: Setting Provide.Strategy to a value with a stray '+' separator: 'pinned+', '+mfs', 'pinned++mfs', or 'all+' — then starting the daemon or calling ParseProvideStrategy/ValidateProvideConfig.

Common situations: Scripted config assembly that appends '+' between tokens unconditionally leaving a trailing separator; hand-editing config.json and leaving a dangling plus; sed/awk joins that produce double separators.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unknown provide strategy token: %q in %q
• "all" strategy cannot be combined with other strategies in %
• +unique/+entities must combine with pinned and/or mfs in %q
• Routing.AcceleratedDHTClient option is set even tho Routing.
• invalid configuration: Provide.DHT.MaxWorkers cannot be 0 wh

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