ipfs/kubo · error

unknown provide strategy token: %q in %q

Error message

unknown provide strategy token: %q in %q

What it means

ParseProvideStrategy splits Provide.Strategy on '+' and recognizes only: all/flat, pinned, roots, mfs, unique, entities. Any other token hits the default branch and returns this error naming both the bad token and the full strategy string.

Source

Thrown at config/provide.go:164

			// 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)
	}
	// +unique/+entities require a base strategy that walks DAGs (pinned and/or mfs)
	wantsDedup := strategy&(ProvideStrategyUnique|ProvideStrategyEntities) != 0
	if wantsDedup {
		walksDAGs := strategy&(ProvideStrategyPinned|ProvideStrategyMFS) != 0
		if !walksDAGs {
			return 0, fmt.Errorf("+unique/+entities must combine with pinned and/or mfs in %q", s)
		}
		if strategy&ProvideStrategyRoots != 0 {
			return 0, fmt.Errorf("+unique/+entities is incompatible with roots in %q", s)
		}
	}
	return strategy, nil

View on GitHub (pinned to 329838acdf)

Solutions

  1. Replace the token with a valid one: all|flat, pinned, roots, mfs, unique, entities — e.g. ipfs config Provide.Strategy 'pinned+mfs'
  2. Check the current vocabulary in docs/config.md under Provide.Strategy for your kubo version
  3. If migrating from an old value like 'flat', note it is now a synonym of 'all': ipfs config Provide.Strategy all

Example fix

// before
ipfs config Provide.Strategy 'pins+mfs'
// after
ipfs config Provide.Strategy 'pinned+mfs'
Defensive patterns

Strategy: validation

Validate before calling

validTokens := map[string]struct{}{"all": {}, "flat": {}, "pinned": {}, "roots": {}, "mfs": {}, "unique": {}, "entities": {}}
for part := range strings.SplitSeq(s, "+") {
	if _, ok := validTokens[part]; !ok {
		return fmt.Errorf("unknown token %q", part)
	}
}

Type guard

func isValidStrategyToken(t string) bool {
	switch t {
	case "all", "flat", "pinned", "roots", "mfs", "unique", "entities":
		return true
	}
	return false
}

Try / catch

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

Prevention

When it happens

Trigger: Setting Provide.Strategy containing an unrecognized token — e.g. 'everything', 'pins' (singular), 'flat+unique' with a typo like 'flatt', or an old strategy name removed in newer kubo — at daemon startup or via ValidateProvideConfig.

Common situations: Copying a strategy string from an older kubo version or another implementation with different vocabulary; misremembering token names ('pins' vs 'pinned'); typos in deployment automation.

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

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